Worker won't start

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 reattach handshake. This page walks through each.

Stage 1: worker install fails

The install command does several things in order:

1. Creates the worker record on the server.
2. Writes local config to ~/.justtunnel/workers/<name>/.
3. Registers the unit with launchd / systemd.
4. Bootstraps (starts) the unit.

A failure in any of those steps surfaces as a different error.

local config write failed; rolled back server-side create

Step 2 failed. Disk full, permissions on ~/.justtunnel/, or the parent directory doesn't exist. The CLI rolled back the server-side worker so you don't end up with a phantom record.

Fix. Resolve the disk/permissions issue and retry.

bootstrap supervisor for "<name>" failed

Steps 1 and 2 succeeded; step 3 or 4 failed. The CLI's hint suggests retrying the install or running justtunnel worker uninstall <name> to roll back.

Fix.

# Try once more
justtunnel worker install my-worker
 
# If it still fails, roll back and start clean
justtunnel worker uninstall my-worker

If uninstall itself fails with stop supervisor: ..., add --force to clean up local state regardless:

justtunnel worker uninstall my-worker --force

macOS-specific: launchctl wedged

On macOS, launchctl bootstrap can fail with various opaque errors. The most common cause is a stale unit from a previous install that wasn't fully removed.

Fix.

# List jt 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-worker

Linux-specific: systemd --user linger consent

On Linux, systemd --user units only run when a session is active unless you enable lingering for the user. By default the installer prompts; pass --no-linger to skip the prompt and accept that the worker is session-bound.

Fix. Either enable lingering manually:

sudo loginctl enable-linger $USER

…or accept session-bound behavior by re-running install with --no-linger. A session-bound worker stops when you log out.

Stage 2: Worker 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 --follow

Common patterns:

• Auth failures. API key was rotated; the worker config is stale. Reinstall the worker.
• Local target unreachable. The local 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 empty

The local config exists but launchd / systemd doesn't know about the unit. This happens if the supervisor was reset (logout, OS upgrade) without worker uninstall first.

Fix. Reinstall:

justtunnel worker uninstall my-worker --force
justtunnel worker install my-worker

Stage 3: Worker connects, then immediately disconnects

The handshake succeeds but the server closes the connection. The CLI surfaces the close code and reason in the logs. The four worker-attach close codes are:

Code	Reason	What to do
4404	worker_not_found	The worker name isn't in the API key's team. Reinstall, or check you're in the right context.
4423	worker_suspended	An admin suspended the worker. Lift suspension in the dashboard before reattach.
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.

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 200

If all three are healthy but the tunnel URL still 404s, the issue is at the proxy / subdomain layer, not the worker. See Subdomain conflict.

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
• Worker tunnel guide
• Disconnects and reconnects
• Subdomain conflict