GUIDE · Errors

n8n 401 Unauthorized: Every Cause and Its Fix (Complete Map)

2026-10-23 · William Ayad · 10 min read

A 401 Unauthorized in n8n means one thing precisely: the external provider rejected the credential your node presented. n8n itself is fine — it faithfully delivered a key the other side refused. That reframing is the fix's entire beginning, because it moves your investigation from the canvas to the credential. This guide is the complete map: how a 401 differs from its look-alikes, the decision tree that isolates your exact cause in three minutes, the four provider-specific patterns that account for most real cases, and the deployment trap that makes the editor lie to you.

401 vs. 403 vs. 429 — read the number correctly first

The status code is the provider's sentence about you. 401: "I don't know who you are" — authentication material missing, malformed, expired, or revoked. 403: "I know you, and no" — identified but forbidden: missing OAuth scopes, a role without permission, a feature outside your plan. 429: "slow down" — rate limiting, a traffic problem, not an identity problem. The full translation table of n8n error shapes lives in the error-codes guide; here we go deep on the 401 family only. One practical caveat: providers blur the standard. Several well-known APIs return 401 for missing scopes that "should" be a 403 — so when a key you are certain of still 401s, check permissions and scopes as if the code had been 403. The number narrows the hunt; it does not finish it.

The decision map — find your exact 401 in three minutes

Answer three questions in order; each answer removes a whole branch of causes.

1. Did this credential ever work in n8n? If never: you are in setup territory — wrong key type, key value pasted with whitespace, wrong auth method selected on the node, or (for OAuth) a handshake the provider refused; jump to the provider patterns below. If it worked and broke later: you are in lifecycle territory — something expired, was revoked, or was rotated. Nothing about your workflow changed; the world around the credential did.

2. What auth type is the node using? OAuth2 credentials fail by lifecycle (token expiry, revoked grants, lost refresh) — the deep dive on that pattern is the 7-day expiry piece. API keys and Personal Access Tokens fail by administration (revocation, rotation, scope edits) — they do not expire on their own. Basic and Header auth fail by configuration (wrong field, wrong encoding, wrong header name). The error text usually names its family: invalid_grant is OAuth death being announced;Invalid API key / invalid_auth is key administration.

3. Does it fail everywhere, or only on scheduled runs? If manual executions pass and automatic ones 401, skip to the editor-lies section — you are dealing with two different execution environments, and the credential exists in only one.

The four provider patterns behind most real-world 401s

Google: invalid_grant is a lifecycle report, not a password error

Gmail, Sheets, Drive and Calendar 401s surface as invalid_grant: the refresh token was rejected — revoked by Testing-mode consent screens (the 7-day cycle), by password changes, by revocation pages, or by Google's per-client live-token cap when too many re-authorizations pile up. The full repair sequence, including redirect_uri_mismatch during the handshake, is in the Google OAuth guide — read it before touching anything Google-shaped.

Microsoft: the one-hour token and the .default scope trap

Outlook, Teams and SharePoint credentials that die after roughly an hour share one root: the OAuth app requested the .default scope, and Azure does not reliably issue a usable refresh token against it — the community evidence is consistent. Use explicit scopes (offline_access plus the specific resource scopes), the v2.0 endpoints, and expect work/school tenants to apply their own idle-expiry policies on top — often 14 days of inactivity kills the grant under organizations' default rules.

Slack: rotation and scopes quietly diverging

Slack answers bad tokens with invalid_auth / token_revoked inside a 401-class response. Two causes dominate: token rotation enabled on the Slack app (stored tokens die on a schedule someone else controls) and scopes edited after the credential was authorized — the token still identifies you, but no longer matches what the app now requires. Re-authorize after any scope change, and treat rotation settings as a shared-calendar obligation for whoever owns the Slack app.

Airtable and the PAT era: revoked keys that never "expire"

Since Airtable retired legacy API keys, personal access tokens carry scoped access — and scoped access means the token can be perfectly valid while schema.bases:read or the specific base grant is missing. Airtable 401/403 responses with an otherwise correct key are almost always a scope or base-allowlist gap in the PAT settings, not a paste error. Review the PAT's scopes and resource list in Airtable's builder hub before rotating anything.

When the editor lies: works manually, 401s on schedule

This is the 401 pattern that costs people whole evenings, because every manual test passes. The explanation is architectural: editor tests run on the main n8n process; scheduled and webhook runs execute elsewhere — in queue mode, on separate worker containers with their own environment. Database-stored credentials are shared and safe; but credentials injected through environment variables or credential files exist only where you mounted them. Main has the file; workers do not; Monday's 6 AM run 401s while your 6:05 AM editor test smiles. The fix is either aligning the environment across every container, or moving the credential into the database where queue mode expects it. While auditing the deployment, confirm the instance URL story too — OAuth callbacks and webhooks share the same localhost triangle covered in the webhook-not-firing ladder.

The generic node: hand-rolled headers in HTTP Request

A large share of stubborn 401s never touch a credential object at all — they live in HTTP Request nodes where somebody set the Authorization header by hand. Three shapes recur. The token pasted as a static string months ago has since expired or been rotated, and the node keeps presenting a corpse. The header value is an expression — =Bearer ... — that resolves empty because the upstream field it reads was renamed; the provider receives "Bearer" with nothing after it. And for Basic auth, the value is the unencoded user:password where the API expected Base64. The steady-state fix for all three is the same: stop hand-rolling. Use the node's built-in authentication types so expiration, encoding and header naming are n8n's problem, not your memory's.

The five-minute field protocol when a 401 hits

Discipline beats brilliance here; run these in order and the average resolution time collapses:

1. Read the exact error text in the failed node's output — not the toast, the full body. It names the family almost every time.
2. Identify the auth type on the node (OAuth / API key / PAT / manual header). The branches diverge here, per the map above.
3. Reproduce manually once. If a manual run passes, the credential is fine and the environment is split — do not rotate anything.
4. Repair in place: reconnect OAuth; edit key values for keys. Check scopes before any recreation.
5. Verify against a real scheduled execution — the only test that proves the production path healed, not the editor path.

Five steps, ordered by cost, ending on the check most people skip. The skipped step is why "fixed" 401s return on Mondays.

Reading raw crash text instead of guessing

Whatever the provider, the execution view leaves the exact rejection in the node's error output — and those strings are more diagnostic than the status code. insufficient authentication scopes points to 403-behind-401. invalid_token vs token_expired separates revocation from time. When the text is unfamiliar, paste it into the free n8n Error Doctor: it pattern-matches the documented crash classes — authentication rejections included — and answers with the class, the underlying cause, and the fix in about two seconds, entirely in your browser. It is the same classification work this article did by hand, compressed into a paste.

Prevention: stop meeting 401s for the first time in production

Three habits end most 401 surprises. First, a rotation calendar: any provider with scheduled death (Meta ~60 days, Xero 60 idle days, Slack rotation) gets a renewal appointment before the token's birthday, not after its funeral. Second, monitor for the absence of success rather than for an error email nobody sends — the alert-on-silence pattern from the monitoring guide is precisely how a Sunday-night credential death gets caught before Monday's users. Third, stop hand-editing credentials on Friday afternoons: changes land on the preflight checklist discipline, where reconnects are verified against a real scheduled execution, not a hopeful manual test.

Frequently asked questions

Does a 401 in n8n always mean my credentials are wrong?

No. It means the provider rejected what was presented — which includes correct values delivered incorrectly: expired OAuth refresh, revoked API keys, keys sent in the wrong header, and credentials that exist in the editor but not on the worker running the job. Right value, wrong delivery is a real sub-class of 401.

Why does the manual test succeed but the scheduled run fail?

Editor tests and real runs can execute in different processes. In queue mode, workers with a different environment run your production executions; environment-injected credentials present on main but absent on workers produce exactly this split. Store credentials in the database or align environments across containers.

Will deleting and recreating the credential fix it?

It can, at hidden cost: every node referencing the old credential must be re-pointed, and missed nodes fail next week instead. Prefer reconnecting in place (OAuth) or editing the key value in place (API keys, PATs). Recreate only for corrupted credential objects or consent grants the provider insists on re-issuing.

What is the difference between 401 and 403?

401: authentication failed — you were not identified. 403: identified but not allowed — scopes, roles, plan limits. Providers blur the line often enough that a stubborn "correct key" 401 deserves a scope and permissions audit.

The one-paragraph answer to bookmark

A 401 is the provider talking, not n8n failing. Read the exact error text, identify the auth type, reproduce manually to separate credential-death from environment-split, repair in place, and prove the fix on a real scheduled execution. OAuth dies by lifecycle; keys die by administration; manual headers die by entropy. Handle the recurring cases systemically — publish consent screens, calendar your rotations, share credentials across workers — and 401 stops being an incident and becomes a footnote.

Where the free tool stops (honesty first)

The Error Doctor classifies crash text from documented field patterns — it does not hold your keys, cannot test them against providers, and cannot see your server environment. The full authentication failure library behind this map — incidence-ranked entries, per-provider rebuild checklists, and the preflight rules that flag credential-risk patterns before they reach production — lives in the n8n Reliability Kit, one-time $19 launch (disclosing: mine), browser-local like the free tools.