ReferenceErrors & recovery

Error reference

These are stable tunnel/edge error codes. Use the specific fix below, then verify the affected part of the connection. Control API HTTP errors can instead return a plain message in an error field; they do not all use this code taxonomy.

Follow the diagnostic checklist
ERR_AUTH_REQUIRED

Authentication required

The edge received a bind without valid credentials.

Fix: Run /login inside the console, or set TRQSH_API_KEY / api_key in ~/.trqsh/trqsh.yml. Restart an existing daemon after changing startup credentials.

ERR_AUTH_INVALID

Invalid credentials

The API key or token was rejected.

Fix: Create a fresh key in the dashboard under API keys and update your config.

ERR_VERSION_UNSUPPORTED

Agent version unsupported

This edge no longer supports your agent's protocol version.

Fix: Use /update inside the console or reinstall through your original package manager. Use /down before relaunching the updated agent.

ERR_QUOTA_TUNNELS

Concurrent tunnel limit reached

Plan limit

You've hit the number of simultaneous tunnels your plan allows.

Fix: Stop an unused tunnel, or upgrade for a higher concurrent limit.

Compare plans
ERR_QUOTA_BANDWIDTH

Bandwidth quota exceeded

Plan limit

The account's transfer allowance for the enforced usage window is used up.

Fix: Check the account usage window, wait for allowance to become available, or choose a plan with more bandwidth.

Compare plans
ERR_QUOTA_REQUESTS

Request quota exceeded

Plan limit

This month's request allowance is used up.

Fix: Check this deployment's request allowance and usage window, then wait or choose a higher limit.

Compare plans
ERR_SUBDOMAIN_TAKEN

Subdomain already taken

Another account has claimed that subdomain.

Fix: Pick a different subdomain, or omit it to get a random one.

ERR_SUBDOMAIN_FORBIDDEN

Subdomain not permitted

The requested name is not reserved by the account binding the tunnel, or reserved names are not permitted.

Fix: Use /subdomains reserve NAME or the dashboard's Domains page, then bind using the same account. Check reservation limits separately.

ERR_DOMAIN_UNVERIFIED

Custom domain not verified

The custom domain hasn't completed DNS verification.

Fix: Add the TXT and CNAME records shown in the dashboard, then re-verify.

ERR_PLAN_FORBIDS

Not available on your plan

Plan limit

The feature you requested (for example UDP or a custom domain) isn't allowed by your effective plan.

Fix: Check the effective plan and its expiry, then use an allowed feature or upgrade. Protocol availability also depends on the edge deployment.

Compare plans
ERR_PROTO_UNSUPPORTED

Unsupported protocol

The tunnel protocol you asked for isn't available on this edge.

Fix: Use the documented HTTP, TCP or UDP workflow supported by your edge. Core HTTPS/TLS identifiers do not guarantee HTTPS upstream forwarding or SNI passthrough.

ERR_PORT_UNAVAILABLE

Remote port unavailable

The requested TCP/UDP remote port is already in use.

Fix: Choose an available port in the edge's configured pool, or omit remote_port. On a self-hosted edge, also publish/open the assigned port.

ERR_RATE_LIMITED

Rate limited

Plan limit

You're opening connections or making requests too quickly.

Fix: Back off and retry; upgrade for a higher rate limit if you hit it often.

Compare plans
ERR_INTERNAL

Internal error

Something went wrong on the edge.

Fix: Retry shortly. If it persists, check status or contact support.

ERR_UPSTREAM_UNREACHABLE

Local service unreachable

The edge reached your agent, but the agent couldn't connect to your local service.

Fix: Confirm your local server is running on the address you tunneled (e.g. localhost:3000).