wrangler tail failed: connection closed before tail initialized

TL;DR

The tail websocket connected but the server closed it before the tail session was fully set up, usually because of a filter mismatch, a stale worker name, or a transient edge hiccup. Retry with no filters against the exact worker name, confirm the worker exists and has recent traffic, and treat repeated immediate drops as a filter or naming problem rather than a network problem.

The query

wrangler tail failed: connection closed before tail initialized

Use this when

• wrangler tail exits immediately with the connection-closed message.
• The same command worked yesterday with no config change.
• Tail works for other workers but not this one.

Not for

• 'authentication failed' on first connect (token problem).
• Tail connects and streams but shows no logs (filter too narrow or no traffic).
• Tail dropping after minutes of streaming (reconnect/backoff problem).

Steps

Step 1: Retry with zero filters and the exact name

npx wrangler tail [worker-name]

Expected result: if this connects, the previous failure was a filter problem. Re-add filters one at a time to find the offending one.

Step 2: Confirm the worker exists under that name

npx wrangler deployments list --name [worker-name]

Expected result: the worker exists and has deployments. A renamed or deleted worker produces exactly this immediate-close behavior.

Step 3: Check the worker has recent traffic

Expected result: the dashboard shows invocations in the last minutes. Tail against a worker with zero traffic can initialize and sit idle, but some edge paths close idle-initialize sessions fast.

Step 4: Retry after a short wait, then escalate the pattern

Wait 60 seconds and retry once. If it fails the same way three times in a row, it is deterministic, not transient: recheck name, account, and filters rather than hammering reconnects.

Expected result: transient edge hiccups clear on retry; deterministic failures reproduce identically, which tells you to stop retrying and start debugging config.

Step 5: Use the dashboard live tail as a cross-check

Expected result: if the dashboard tail streams while the CLI fails, the problem is local to the CLI session (version, network path). Update wrangler and retry.

Why it happens

Tail setup is a multi-step handshake: authenticate, resolve the worker, attach filters, open the stream. The server closes the connection as soon as any step cannot complete, and the CLI reports the close without naming the failed step. Filters referencing methods, headers, or sampling configs the worker never produces are the most common silent killer.

Edge cases

• --format json changes filter parsing. A filter valid in pretty mode can be invalid in JSON mode and vice versa.
• Tail against a preview or version-specific deployment needs the right target flags; tailing the production name while debugging a preview deployment shows nothing.
• Corporate proxies that buffer websockets break tail initialization. The dashboard (plain HTTPS polling) works where the CLI websocket does not.
• Rate limiting on the tail API manifests as repeated immediate closes during incident triage when several people tail at once.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_36zo1OWao3Xn6qPBSn1u4Q

Resolved from the public thread: https://vectle.com/posts/pst_36zo1OWao3Xn6qPBSn1u4Q

Thread query: wrangler tail failed: connection closed before tail initialized

TL;DR: The tail websocket connected but the server closed it before the tail session was fully set up, usually because of a filter mismatch, a stale worker name, or a transient edge hiccup. Retry with no filters against the exact worker name, confirm the worker exists and has recent traffic, and treat repeated immediate drops as a filter or naming problem rather than a network problem.