Report bugs and issues
Send problems you cannot solve to support@netzilo.com. A report with the facts below can be investigated straight away. One without them usually comes back with questions first.
Before you write, rule out the common causes in Troubleshooting client issues: another VPN, a wrong clock, an unfinished captive portal, a policy that does not cover the two peers.
Never send credentials. Do not include access tokens, setup keys, passwords or private keys in a report, an e-mail body or an attachment. On Windows the client's debug bundle contains some of these; remove them as described in Remove credentials.
What to include
The problem
- What happens, with the exact error text, and where it appears (dashboard, client, browser, agent).
- What you expected, and the setting that says so: the policy, route, filter or guardrail by name.
- How often: every time, now and then, or once. The shortest steps that reproduce it.
Impact and severity
| Severity | Meaning |
|---|---|
| S1 | nobody can work and there is no workaround: control plane down, every peer disconnected, nobody can sign in |
| S2 | a group or a site is blocked; the workaround is painful |
| S3 | one user or device; a workaround exists |
| S4 | a suspected defect with no outage, or a documentation error |
Say how many users and devices are affected, since when, and what changed just before: an upgrade, a policy edit, a certificate, a network change.
The facts that make logs readable
- The exact time of an occurrence, with the time zone.
- The client version (
netzilo version). For a self-hosted server, the image versions (docker compose images). - The affected peer's Netzilo IP, name (FQDN) and WireGuard public key, from
netzilo status -d. - The user's e-mail address, or the name of the setup key the device enrolled with.
- The deployment: Netzilo Cloud, or a self-hosted Netzilo Server with its install path (on-premises, AWS, Azure) and domain.
Collect from the device
On the affected device, raise the log level, reproduce the problem, then collect:
Linux and macOS
netzilo debug log level trace
# reproduce the problem now
sudo netzilo debug bundle
netzilo status -d > ~/netzilo-status.txt
netzilo version >> ~/netzilo-status.txt
sudo cp /var/log/Netzilo.err.log ~/ 2>/dev/null # macOS only, not in the bundle
Windows (PowerShell as Administrator)
netzilo debug log level trace
# reproduce the problem now
netzilo debug bundle
netzilo status -d | Out-File "$env:USERPROFILE\netzilo-status.txt"
Send the zip path that debug bundle prints, and netzilo-status.txt. Set the log level
back with netzilo debug log level info.
- Use the CLI, not the tray's Support > Collect Data: the tray bundle has no status snapshot.
- Do not anonymize the bundle by default (
-A). Anonymizing breaks the link between the status file and the logs. Use it only when your policy requires it, and say so in the report. - Avoid
netzilo debug for: it logs the device out.
Remove credentials before you send
On Windows the bundle includes the client's configuration folder. Open the zip and delete these files before you send it:
config.json(contains the WireGuard private key)token.datandpat.datnetzilo-ca-key.pem- every
usservice*.json mcp.db, if present- any workspace
.jsonfile next to them
Keep the log files: they are the evidence. If you cannot edit the zip, do not send it. Send the status file and the relevant log lines instead, and say that the bundle was withheld.
Logs written at debug or trace level can contain tokens or connection strings. Read
the lines you send.
Collect from a self-hosted server
On Netzilo Cloud, Netzilo already has the server logs; do not send any. Give the account and the time window instead.
On a self-hosted server, the management log is the most important file. Collect it over a window from one hour before the first occurrence to one hour after the last:
cd /opt/netzilo/run 2>/dev/null || cd /opt/netzilo
sudo docker compose ps > ~/netzilo-server.txt
sudo docker compose images >> ~/netzilo-server.txt
for s in management zitadel caddy signal coturn; do
sudo docker compose logs --no-color --timestamps --since 24h $s > ~/netzilo-$s.log
done
Say in the report which window, in UTC, the logs cover. Never send management.json,
zitadel.env, dashboard.env, .env, turnserver.conf, the CREDENTIALS file,
certificates, keys or database dumps.
AI Gateway problems
For a problem with an agent calling the Netzilo AI Gateway, add:
netzilo-aigw --versionand the last hour ofjournalctl -u netzilo-aigw.- The gateway's
runflags, without--service-pat,--pat,--setup-keyand theNZ_GATEWAY_*values. - The failing request's status code and response body, without the token. The body's
typefield says which part of the gateway refused it.
Report from the dashboard assistant
An administrator can also ask the dashboard's AI assistant to prepare the report. It collects what it can through the API and the device tools, writes the summary, and asks the administrator to approve before anything is sent. Where escalation is not set up for your deployment, it gives the administrator the summary to send to support@netzilo.com. Regular users hand the case to their administrator.
Related Documentation
- Troubleshooting client issues - rule out the common causes first
- CLI -
netzilo status,debug bundleanddebug log level - Troubleshooting - self-hosted server problems
- AI Gateway - gateway refusals and logs

