Troubleshooting

Most problems fall into one of two buckets: the agent can't authenticate or connect, or a visitor can't reach your tunnel. The Traffic Inspector shows every request that reaches the edge and is the fastest way to tell whether traffic is arriving at all.

"invalid or missing osmRouter token"

The agent couldn't authenticate. OSM_TOKEN is unset, malformed, or revoked.

Confirm it's exported in the shell you're running from: echo $OSM_TOKEN should print a value starting with osm_.
If it was copied with surrounding quotes or whitespace, re-copy it cleanly.
If it was deleted under Tokens, create a new agent token and re-export it.

export OSM_TOKEN=osm_xxxxx
osmrouter http 8080

Exports are per-shell. A new terminal won't have OSM_TOKEN unless you add the export to your shell profile (~/.zshrc, ~/.bashrc).

"This tunnel is offline"

The hostname resolves, but no agent is currently bound to it.

Make sure an agent is actually running. The process must stay in the foreground (or under a supervisor) — closing the terminal kills it.
If you expect a fixed URL, pin the subdomain. Without OSM_SUBDOMAIN every run gets a fresh random name, so the old URL goes offline:

OSM_SUBDOMAIN=my-app osmrouter http 8080

Check the agent's own logs. If it printed a connection error, the tunnel never came up in the first place.

"Tunnel limit reached"

You've hit the maximum number of concurrent tunnels for your plan (10 on Free, 1,000 on Pro).

Stop an idle agent (Ctrl-C) to free a slot.
List what's currently live to find strays:

curl https://api.osmrouter.com/v1/tunnels \
  -H "Authorization: Bearer $OSM_TOKEN"

"Bandwidth limit reached"

You've consumed your monthly transfer quota (50 GB on Free, 1 TB on Pro).

Check where you stand with GET /v1/usage.
Use the Traffic Inspector to find heavy endpoints — response size is shown per request.
Quotas reset monthly; upgrade to Pro for headroom sooner.

Custom domain won't verify

Verification fails until the DNS TXT record is visible from public DNS.

Add the exact record — name _osmrouter.<your-host>, value osm-verify-....
Confirm it has propagated before retrying:

dig +short TXT _osmrouter.example.com
# expect: "osm-verify-..."

DNS propagation can take a minute to a few hours depending on your provider's TTL. If dig doesn't return the value yet, Verify will fail — wait and retry rather than re-adding the domain. Watch for a doubled zone suffix like _osmrouter.example.com.example.com, the most common mistake.

Streaming client hangs or times out

If a stream appears to hang, the tunnel is almost always fine — a non-streaming client is calling a streaming upstream and buffering the whole body.

# Hangs: curl waits for a full body that streams forever
curl https://my-llm.osmrouter.com/v1/chat/completions -d '{...,"stream":true}'

# Works: consume the stream as it arrives
curl -N https://my-llm.osmrouter.com/v1/chat/completions -d '{...,"stream":true}'

With curl, add -N (--no-buffer).
In an SDK, use the streaming API rather than awaiting .text() / .json().
If you don't want streaming, set "stream": false on the upstream.

502 at the edge

A 502 means the edge reached your agent but the agent couldn't reach your local service. Confirm the service is actually listening on that port before tunneling — a refused connection locally surfaces as a 502.

Still stuck?

Check osmrouter version and re-run against a known-good local service.
Pro plans include priority support. Self-host deployments come with an SLA.
Still need a hand? Email contact@osmapi.com.

On this page