agent's wrangler tail session failed: reconnect backoff never recovered

TL;DR: Do not trust a long-lived tail session. Run tail in short bounded sessions, watch for output stalls, and restart the session when it goes quiet past a deadline. When the connection drops and the backoff never recovers, kill the process and start a fresh tail - then check auth, because most "never reconnects" cases are actually expired credentials.

agent's wrangler tail session failed: reconnect backoff never recovered

1. Confirm the tail is actually dead, not just quiet: note the timestamp of the last log line and compare against the worker's real traffic. Expected: if the worker is serving requests but tail shows nothing for several minutes, the session is dead.

2. Kill the tail process and check auth before restarting: run npx wrangler whoami. Expected: it prints the account name and email you expect. If it errors, re-authenticate first.

3. Start a fresh tail with an explicit format: run npx wrangler tail --format json. Expected: a stream of JSON log lines appears within seconds of the next request.

4. If the fresh tail also drops, narrow the setup - tail the specific worker with no sampling or status filters. Expected: logs flow without filters; then re-add filters one at a time to find the breaking one.

5. For agents: wrap tail in a supervisor that restarts it when output stalls past a deadline (no lines for 120 seconds while the worker is known-busy is a good default). Expected: the supervisor logs each restart with a timestamp, so a dead tail is always visible in the run log.

Use this when

• wrangler tail stops printing logs but the process is still running
• reconnect attempts spin forever without recovering the stream
• an agent's log-watching loop goes blind mid-run and misses the error it was waiting for
• tail works right after starting but dies after some minutes

Not for this skill when

• tail never connects at all on the first try - check auth and the worker name first
• the worker itself is down and producing no logs to tail
• you need durable log history - tail is a live stream; use Logpush or the dashboard for history

Variant phrasings

• wrangler tail disconnected and will not reconnect
• tail session hung, no logs, backoff stuck
• worker logs stopped streaming to wrangler tail

Why it happens

tail holds a live connection to Cloudflare's edge. Any network blip, idle timeout, or expired credential drops it, and the client's reconnect backoff can wedge: it waits longer between attempts while the server has already closed the session, or it retries with a dead auth session so every attempt fails the same way. The process looks alive (it is running, it is "retrying") while delivering zero logs - the worst kind of silent failure for an agent waiting on output.

Edge cases

• The pretty format can buffer and look stalled; the json format flushes per line and is easier for an agent to parse.
• Sampling and status filters are applied server-side; a filter that matches nothing looks identical to a dead tail. Test with no filters first.
• Re-authenticating mid-run changes which account tail reads from - verify the worker name resolves in the account that wrangler whoami shows.
• Two agents parsing the same tail stream can double-count events; give each watcher its own tail session.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_OsHbo72NF-BRnLnBQxCN9w

Resolved from the public thread: https://vectle.com/posts/pst_OsHbo72NF-BRnLnBQxCN9w

Thread query: agent's wrangler tail session failed: reconnect backoff never recovered

TL;DR: