Subdomain conflict
Why the CLI rejects a subdomain you asked for, and what each of the three rejection reasons actually means.
When you ask for a specific subdomain — with --subdomain, in tunnels.yaml, or as a worker tunnel's stable name — the server can refuse for one of three reasons. The CLI surfaces all three as server returned 403 with a hint that says it's not an auth problem. This page tells you which of the three you actually hit.
The three reasons
The server's 403 hint names them directly:
Common causes: requested subdomain requires the Pro plan, the subdomain is in use, or your account/team is suspended.
Work through them in this order.
Reason 1: Reserved subdomains require Pro
This is the most common one. Free and Starter plans get random subdomains only. Asking for a specific name on those tiers fails with the server-side code RESERVED_SUBDOMAIN_NOT_ALLOWED.
How to confirm. Run with verbose logging:
justtunnel 8080 --subdomain my-thing -vIf the error message includes RESERVED_SUBDOMAIN_NOT_ALLOWED or "Reserved subdomains require a Pro plan", this is your case.
How to fix.
- Drop the
--subdomainflag and let the server pick a random name. Free/Starter tunnels work fine with random subdomains. - Or upgrade to Pro and reserve the name in the dashboard. See Reserve a subdomain.
Reason 2: The subdomain is in use
You're on Pro (or the name doesn't require Pro), but the name is already attached to a connected tunnel. Subdomains are exclusive — one connected tunnel per name at a time.
How to confirm. Check the dashboard's tunnels list, or run justtunnel status to see what's connected under your account.
justtunnel statusIf a tunnel with that subdomain is listed and you didn't expect it to be, you may have left a justtunnel running in another terminal, or a worker tunnel may already own the name.
How to fix.
- Stop the tunnel that's holding the name. If it's a worker, see Worker tunnels for the right way to stop it.
- If you reconnected within 24 hours of a previous session, the previous reconnect token may still be holding the name. Wait briefly or pick a different subdomain — see Disconnects and reconnects.
- If you genuinely don't know what's holding the name, open an issue — sometimes a stale registry entry is the cause.
Reason 3: The name is in the reserved-words list
JustTunnel reserves a list of subdomains that no user can claim — names like api, admin, www, dashboard, plus brand-protected names. If you ask for one of those, the server refuses even on Pro. The server-side code is RESERVED_SUBDOMAIN_NOT_ALLOWED (same code as the plan-tier case, but the cause is different).
How to fix. Pick a different name. There's no mechanism to claim a reserved word.
Reason 4: Account or team suspended
If the subdomain you asked for is one you've used before and the answer is suddenly no, check whether the account or team was suspended (abuse detection, payment failure, etc.). Suspension blocks all tunnel creation, not just the named one.
How to fix. See Abuse detection FAQ for the abuse-related case, or check billing status in the dashboard.
Worker tunnels and subdomain conflicts
Worker tunnels derive a stable subdomain from the worker name and the team. If the worker's intended subdomain conflicts with an existing reservation, justtunnel worker install rejects the install up front rather than letting you create a worker that can never connect. The CLI message names the conflicting subdomain.
How to fix. Pick a different worker name, or release the conflicting reservation in the dashboard.
Diagnosing quickly
A short decision tree:
| Symptom | Likely reason |
|---|---|
| Free/Starter plan, asking for a name | Reason 1: needs Pro |
| Pro/Team plan, name is one you've used | Reason 2: stale tunnel still attached |
Pro/Team plan, asking for api/admin/www | Reason 3: reserved word |
| Worked yesterday, broken today | Reason 4: check account/team status |
Still stuck?
If you've ruled out all four reasons, open an issue with the exact command, the subdomain you asked for, and the full error output (-v flag).