Troubleshooting
Diagnose a worker tunnel that won't install, won't start, or won't stay connected.
Worker tunnels are long-lived tunnels supervised by the OS service manager (launchd on macOS, systemd --user on Linux). When something goes wrong, the failure happens in one of three places: the install step, the supervisor, or the server reattach handshake.
Quick sanity checks
# Is the worker registered locally?
justtunnel worker list
# What does the supervisor think?
justtunnel worker status my-worker
# What did the worker process actually log?
justtunnel worker logs my-worker --tail 200If all three are healthy but the tunnel URL still 404s, the issue is at the proxy / subdomain layer, not the worker. See Subdomain conflict.
Stage 1: worker install fails
The install command does several things in order:
- Creates the worker record on the server.
- Writes local config to
~/.justtunnel/workers/<name>/. - Registers the unit with
launchd/systemd. - Bootstraps (starts) the unit.
A failure in any step surfaces a different error.
local config write failed; rolled back server-side create
Step 2 failed. Disk full, wrong permissions on ~/.justtunnel/, or the parent directory doesn't exist. The CLI rolled back the server-side worker record so you don't end up with a phantom entry.
Fix: Resolve the disk or permissions issue and retry worker install.
bootstrap supervisor for "<name>" failed
Steps 1 and 2 succeeded; step 3 or 4 failed.
Fix:
# Retry once
justtunnel worker install my-worker
# If it still fails, roll back cleanly
justtunnel worker uninstall my-worker
# If uninstall also fails, force it
justtunnel worker uninstall my-worker --forcemacOS: launchctl wedged
A stale unit from a previous install that wasn't fully removed can wedge launchctl bootstrap.
Fix:
# List JustTunnel worker units
launchctl list | grep justtunnel
# Manually unload anything stale
launchctl bootout gui/$(id -u) /path/to/com.justtunnel.<name>.plist
# Then re-run install
justtunnel worker install my-workerLinux: systemd user-linger
systemd --user units only run when a session is active unless you enable lingering. The installer prompts for this; if you declined, the service is session-bound.
Fix (to run across logout):
sudo loginctl enable-linger $USER
# Then re-run install to refresh the unit
justtunnel worker uninstall my-worker
justtunnel worker install my-workerOr accept session-bound behavior by re-running install with --no-linger.
Stage 2: Installed but won't run
worker install succeeded but worker status shows the worker as not running.
worker status reports failed or repeated restarts
Pull the logs:
justtunnel worker logs my-worker -fCommon patterns:
- Auth failures. API key was rotated; the local worker config is stale. Run
worker uninstall my-worker && worker install my-workerto reinstall with fresh credentials. - Local target unreachable. The service the worker proxies to isn't running. See Local target unreachable.
- 403 / subdomain conflict. The worker's stable subdomain is taken. See Subdomain conflict.
worker status reports unknown or supervisor is empty
The local config exists but launchd / systemd doesn't know about the unit. This usually happens if the supervisor was reset (OS upgrade, logout on Linux without linger) while the local config was left behind.
Fix: Reinstall:
justtunnel worker uninstall my-worker --force
justtunnel worker install my-workerStage 3: Connects, then immediately disconnects
The handshake succeeds but the server closes the connection. The CLI surfaces the close code in the logs. The four worker-attach close codes are:
| Code | Reason | What to do |
|---|---|---|
| 4404 | worker_not_found | Worker name not found in the team. Reinstall, or check you're in the right context. |
| 4423 | worker_suspended | An admin suspended the worker. Lift the suspension in the dashboard. |
| 4410 | worker_retired | Terminal — the worker was retired or quarantined. Create a new worker. |
| 4409 | worker_in_use | Another session already holds the attachment. Stop the other process or wait for the existing session's grace period. |
A fifth condition is team_subscription_canceled — the team's billing lapsed. Resolve billing in the dashboard.
Common error messages
worker commands require a team context
You're on personal. Run justtunnel context use team:<slug> first.
worker install is not supported on windows
Windows has no managed-service adapter. Use worker start <name> in the foreground under your own supervisor (Task Scheduler, NSSM). See Platform support.
403 from worker start
Most often the worker was created with worker create but never had a service token provisioned. Run worker install <name> to fix it. Other causes: team suspended, membership revoked.
worker rm did not stop the service
rm only removes local config (and optionally the server record) — it does not touch the supervisor. Use worker uninstall for a managed worker.
Linger configuration failed (Linux)
The unit is installed but system-wide linger is not enabled. The worker runs in the current session but stops on logout. Re-run worker install after running sudo loginctl enable-linger $USER, or accept session-bound behavior.
Still stuck?
Open an issue with:
- Output of
justtunnel worker status <name> - The last 200 lines of
justtunnel worker logs <name> - Your platform (macOS version / Linux distro)
Related
- Worker tunnels overview — concept and limits overview.
- Install & manage — full install and teardown walkthrough.
- Platform support — platform-specific supervisor details.
- Disconnects and reconnects — general reconnect troubleshooting.
- Subdomain conflict — when the URL returns 404.