wrangler tail: "authentication failed" on first connect

TL;DR

wrangler tail opens a websocket to the Cloudflare API and is pickier about credentials than one-shot commands. Re-authenticate (wrangler logout, then log back in or set a fresh API credential), confirm wrangler whoami shows the right account, and retry tail. The usual cause is a stale or scoped credential cached locally that one-shot API calls tolerate but the tail websocket rejects.

wrangler tail: "authentication failed" on first connect

1. Check who wrangler thinks you are:

wrangler whoami

Expected: your account email and account ID print cleanly. If this fails too, the credential is dead; skip to step 3.

1. Inspect how you are authenticated. If you use an API token, confirm it still exists in the Cloudflare dashboard under My Profile, API Tokens, and that it has not expired or been rolled. If you use OAuth login, note that browser logins can silently lose scope after permission changes.

Expected: you know which credential wrangler is using and it looks alive.

1. Clear it and re-authenticate from scratch:

wrangler logout
wrangler login

Or, in headless/CI environments, create a fresh API credential with Workers and account read scopes and export it for the shell running tail.

Expected: wrangler whoami now succeeds and shows the correct account.

1. Retry tail with an explicit environment if you use named envs:

wrangler tail --env production

Expected: the tail session connects and prints "Connected to tail, waiting for logs". The first-connect failure is gone.

1. If it still fails, check for a proxy or firewall stripping the websocket upgrade. tail needs a websocket to the Cloudflare API; corporate proxies that allow HTTPS but block websockets produce auth-looking failures.

Expected: on a direct network, tail connects with the same credential that failed behind the proxy.

Use this when

• wrangler tail fails with authentication failed on the first connect.
• tail worked before a token rotation, permission change, or account switch.
• Other wrangler commands work but tail does not.

Not for this skill when

• tail connects but shows no logs. That is a filter or worker-name issue, not auth.
• tail disconnects after running fine for a while. That is a reconnect/backoff issue.
• Every wrangler command fails auth. Fix the credential generally, not tail specifically.

Variant phrasings

• wrangler tail auth error
• wrangler tail websocket authentication failed
• cannot connect wrangler tail unauthorized
• wrangler tail 401 on connect

Why it happens

Most wrangler commands make single HTTPS API calls, which tolerate slightly stale credentials (retries, cached account context). wrangler tail instead opens a long-lived websocket authenticated at handshake time, and the handshake validates the credential strictly, including scopes and account context. A token that was rotated, narrowed in scope, or cached from a different account passes whoami-style checks but fails the websocket handshake, so tail is often the first command to notice a credential went bad.

Edge cases

• Multiple accounts: the credential may be valid but point at an account that does not own the worker. whoami shows the wrong account; tail then fails because the worker is not found under that account, surfaced as auth failure.
• CI runners that inject the credential per-job can have a half-written env var (trailing newline, truncated value). whoami sometimes tolerates it; the websocket does not. Re-export carefully.
• tail --format json with a pretty-printer in the pipe can mask the real error line; run tail bare once to see the raw failure.
• If you recently renamed the worker, tail may be targeting the old name. Pass the current worker name explicitly.

Provenance

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