9.3 KiB
Hanzo Connect troubleshooting
A Hanzo Connect connection goes through four parts, in this order:
- This device reaches Hanzo Connect over the internet.
- Hanzo Connect checks your sign-in and the host's link.
- The host's tunnel (cloudflared on the host) carries the request to the host.
- Hanzo Dev on the host answers.
When a connection fails, open Settings > Environments, find the environment, and select Details. The first part marked as failed is the cause. Find its section below.
To see the host's side, run hanzo connect status on the host, or open
Settings > Sharing & access on the host. Both check the host's Hanzo Connect
address from the host, and say why it fails. hanzo connect runs the same check
when it finishes setup. This check cannot test another device's network. For a
problem on one device, use Details on that device.
The host's tunnel is offline
Hanzo Connect could not reach the host's tunnel. This means one of these:
- The host is asleep, turned off, or offline.
- Hanzo Dev is not running on the host.
- The host's network blocks the tunnel. See Port 7844 is blocked on the host.
Fix:
- Make sure the host is awake and Hanzo Dev runs on it.
- On the host, run
hanzo connect status. It names the problem on the host's side. - If the host was offline for a long time, Hanzo Connect removes its tunnel. Start Hanzo Dev on the host and update it to the latest version. It gets a new tunnel.
Port 7844 is blocked on the host
The tunnel on the host connects out to Cloudflare on port 7844, with TCP and UDP. Both tunnel protocols (QUIC and HTTP/2) use this port. When the host's network blocks it, the tunnel cannot start, but normal web traffic still works. The host looks online, so this problem is easy to miss.
Common causes:
- A Tailscale exit node on the host. All of the host's internet traffic goes
through the exit node, and that network blocks port 7844. Turn off the exit
node on the host with
tailscale set --exit-node=, or allow outbound port 7844 on the exit node's network. - A VPN on the host. Work VPNs often block unknown ports. Ask for port 7844 to be allowed, or use a direct route instead (see below).
- A firewall or strict network. Allow outbound TCP and UDP port 7844.
If you cannot unblock the port, you can connect without Hanzo Connect. When the host and this device are on the same Tailscale network, add the host's Tailscale address as a direct route. See Reach one machine several ways.
The tunnel works, but Hanzo Dev does not answer
The host's tunnel is up, but it cannot reach Hanzo Dev on the host. Common causes:
- Hanzo Dev on the host stopped, crashed, or is still starting.
- Hanzo Dev restarted on a different port, for example after an update, and the tunnel still points at the old port.
- The server binds only one network address with
HANZO_DEV_HOST. The tunnel sends requests to127.0.0.1, so the server must also listen there.
Fix: restart Hanzo Dev on the host. For the background service, run
hanzo service restart. Then run hanzo connect status on the host.
The Hanzo Connect address does not resolve or answer
The host's Hanzo Connect address did not resolve, refused the connection, failed a secure (TLS) connection, or did not answer in time.
Fix:
- Make sure the host is awake and online.
- On the host, run
hanzo connect status. - If the check fails only on the host, check the host's DNS, VPN, or proxy. If it says the host's network has an old cached answer, wait: it usually clears within about 30 minutes.
- If it says the address no longer points to this machine's tunnel, the
environment was likely removed from Hanzo Connect. Link it again: on a desktop
host, turn Hanzo Connect off and on in Settings > Sharing & access. On a
command-line host, run
hanzo connect link, then restart Hanzo Dev.
This device can't reach Hanzo Connect
The problem is on this device's network, not on the host. This device could not reach Hanzo Connect, or it reached Hanzo Connect but not the host's tunnel address.
Fix:
- Check this device's internet connection. On a captive or dead Wi-Fi network, the device can look online but cannot reach anything.
- A VPN, firewall, ad blocker, or DNS filter on this device can block Hanzo Connect. Turn it off for a moment to test.
- On iPhone, Connectivity Assist in the Wi-Fi settings can break Hanzo Connect. Turn it off to test.
- Try another network, or add a direct route to the host, such as its Tailscale address. See Reach one machine several ways.
Sign-in, account, or link problems
This device's Hanzo Connect sign-in is not ready yet, or Hanzo Connect does not have an active link between your account and the host.
- The host is linked to a different account. Sign in to the same Hanzo Connect
account on this device and on the host. On the host, run
hanzo connect logout, thenhanzo connect. - Hanzo Connect is off on the host, or the host only publishes agent activity.
On the host, open Settings > Sharing & access and turn Hanzo Connect on, or
run
hanzo connect. - The host was linked, but the server did not apply the link yet. Restart
the server on the host: quit and reopen the Hanzo Dev desktop app, run
hanzo service restart, or stophanzo serveand run it again. - This device's sign-in expired, or the host no longer accepts this device. Sign out of Hanzo Connect and sign in again.
- This device is still loading its Hanzo Connect sign-in. Wait a moment; Hanzo Dev retries on its own. If it keeps waiting, reload or restart Hanzo Dev on this device.
- The host is waiting for you to approve this device. The host requires
approval for new devices. Approve the code this device shows from a device
that is already connected, or run
hanzo auth connect-device approve <code>on the host. See Approve new devices. - Your account reached its tunnel limit. Remove an environment you do not use from your Hanzo account's Hanzo Connect page, or link a paid Hanzo Chat account for a higher limit. Then restart Hanzo Dev on the host.
The clock is off
Hanzo Connect signs requests with short-lived proofs. When the clock on this device or the host is a few minutes wrong, Hanzo Connect rejects them. Turn on automatic date and time on both devices, then retry.
The host runs an older Hanzo Dev
This app needs a newer Hanzo Dev on the host. Update Hanzo Dev on the host. See Updating Hanzo Dev.
Hanzo Connect returned an error
| Error | Fix |
|---|---|
environment_link_limit_exceeded or managed tunnel limit |
Remove an unused environment or link a paid Hanzo Chat account, then restart Hanzo Dev on the host. |
auth_invalid or invalid_bearer |
Run hanzo connect login. If credentials were revoked, run hanzo connect logout, then hanzo connect again. Restart the server after signing in. |
| Expired or invalid link proof | Check the host's date and time, update Hanzo Dev, then restart it. |
| HTTP 403 without a recognized error | If the host requires approval for new devices, update Hanzo Dev on this device and approve it. Otherwise check relay access, proxies, and firewall rules. Keep any Cloudflare Ray ID for a bug report. |
| HTTP 408, 429, or 5xx | Wait a few minutes. Hanzo Dev retries temporary failures on its own. |
After you fix a permanent rejection, restart the host's server with
hanzo service restart. For a foreground server, stop it and run hanzo serve again.
If Hanzo Dev on the host disappears when SSH closes, see background-service troubleshooting.
Report a problem
If none of this helps, open an issue on GitHub. Include:
- The text from Copy diagnostics in the environment's Details.
- The output of
hanzo connect statuson the host. - The trace ID, if one is shown.
- If the tunnel dropped earlier, the host's tunnel log,
relay-client.ndjsonin the logs folder (~/.hanzo-dev/userdata/logsby default). It records when the tunnel connected, warned, exited, and restarted, with the tunnel token removed.