Skip to main content
AllDevToolsHub
2026-11-13
Last reviewed: Nov 2026
SECURITY
Est Read: 09_MIN

Debugging OAuth 2.0: invalid_grant, redirect_uri_mismatch, and PKCE Failures Explained

Debugging OAuth 2.0: invalid_grant, redirect_uri_mismatch, and PKCE Failures Explained
Processing_Node: 01

#1Debugging OAuth 2.0: invalid_grant, redirect_uri_mismatch, and PKCE failures explained

OAuth error messages are terse by design. RFC 6749 defines a short list of machine-readable error codes and explicitly warns providers against leaking details to a client that might be an attacker. The result for you, the developer who just misconfigured a redirect URI, is a 400 response that says invalid_grant and nothing else.

This guide maps each common error back to the specific request parameter that usually caused it. It covers the authorization code flow with PKCE, which is the flow you should be using for web apps, SPAs, and mobile apps in 2026.

#2Where OAuth errors show up (there are two places)

Before debugging anything, know which half of the flow failed. OAuth errors surface in two different places, and they mean different things.

1. On the redirect back to your app. If the authorization server rejects the initial request or the user denies consent, the error comes back as query parameters on your redirect URI:

protocol
https://app.example.com/callback
  ?error=access_denied
  &error_description=The+user+denied+the+request
  &state=xyz123

These errors are about the authorization request: bad scope, unknown client, user said no.

2. In the JSON response from the token endpoint. If the browser redirect succeeded but the code exchange failed, the error is in the POST response body:

json
{
  "error": "invalid_grant",
  "error_description": "authorization code expired"
}

These errors are about the token exchange: expired code, PKCE mismatch, wrong client credentials.

One exception sits before both of these. redirect_uri_mismatch is usually shown on the provider's own error page, before any redirect happens, because the server refuses to redirect to a URI it does not recognize. If your user never gets back to your app at all, start there.

#2redirect_uri_mismatch: it is an exact string comparison

The authorization server compares the redirect_uri in your request against the registered value as a plain string. Not "same domain", not "close enough". Byte for byte.

The usual culprits, in rough order of how often I have hit them:

RegisteredSentProblem
https://app.example.com/callbackhttps://app.example.com/callback/Trailing slash
https://app.example.com/callbackhttp://app.example.com/callbackScheme
http://localhost:3000/callbackhttp://127.0.0.1:3000/callbacklocalhost is not 127.0.0.1
https://app.example.com/callbackhttps://www.app.example.com/callbackSubdomain
https://app.example.com/callbackhttps://app.example.com/CallbackPath case

Two details worth knowing:

  • The redirect_uri must match at the token endpoint too. If you send redirect_uri in the authorization request, RFC 6749 requires the identical value in the code-exchange POST. Sending it in one and omitting it in the other produces invalid_grant at some providers, which hides the real cause.
  • Query parameters on the redirect URI are allowed by the spec but rejected by several providers. Google, for instance, does not allow them. Put per-request data in state, not in the redirect URI.

The fix is boring: copy the exact registered value from the provider's console into your config, then verify what your app actually sends by capturing the full authorization URL before the redirect fires. The OAuth debugger builds the authorization URL from your parameters so you can diff it against the registered values before involving a real user session.

#2invalid_grant: five different problems wearing one name

invalid_grant is the least specific error in the spec, and the one you will see most. RFC 6749 uses it for any problem with the grant itself. In practice it means one of these:

The authorization code expired. The spec recommends a maximum lifetime of 10 minutes; real providers are often stricter (30 to 60 seconds at some). If there is any delay between the redirect and your server's exchange request, a queue, a cold start, a user staring at a consent screen in another tab, the code dies.

The code was already used. Authorization codes are single use. RFC 6749 says that if a code is used twice, the server should deny the request and should revoke all tokens previously issued for that code. The classic cause is a React app in development: useEffect runs twice under StrictMode, your callback handler fires twice, and the second exchange poisons the first. Deduplicate the exchange, or handle the callback server-side.

The PKCE verifier does not match. Covered in its own section below, because it deserves one.

The redirect_uri differs between the two requests. See above.

The refresh token is expired, revoked, or already rotated. If invalid_grant comes back on a refresh request, the refresh token itself is dead. With rotation enabled (now standard for SPAs), each refresh token is single use, and reusing an old one can trigger reuse detection that revokes the whole session family. If your app stores the refresh token in two places, say memory and localStorage, and they get out of sync, every user gets logged out on a timer and the logs just say invalid_grant.

When you hit invalid_grant, log four things at the point of exchange: the age of the code in seconds, whether this exact code was exchanged before, the redirect_uri you are sending, and the first 8 characters of the code_verifier. One of those four almost always explains it.

#2invalid_client: your credentials never arrived

invalid_client means the token endpoint could not authenticate your app, which is different from the grant being bad. Three common causes:

Wrong authentication method. The spec defines two ways to send a client secret: HTTP Basic auth (client_secret_basic) and form body parameters (client_secret_post). Providers differ in what they accept, and some reject one silently. If you send Basic auth to an endpoint expecting body parameters, the server sees no credentials at all.

Secret characters mangled by Basic auth encoding. With client_secret_basic, the client ID and secret must be URL-encoded before being Base64-encoded into the header. Secrets containing +, /, or = break naive implementations. If your secret has special characters and Basic auth fails but body post works, this is why.

A public client sending no secret where one is expected. If you registered the app as "confidential" but built it as a SPA with no secret, the token endpoint expects authentication that never comes. Re-register the client as public with PKCE required.

#2PKCE failures: three rules, all string-level

PKCE (RFC 7636) binds the authorization code to the client instance that requested it. You generate a random code_verifier, send its SHA-256 hash as the code_challenge, then prove possession by sending the plain verifier at exchange time. The server hashes what you send and compares.

A PKCE failure surfaces as invalid_grant (or occasionally invalid_request). The rules that get broken:

  1. The verifier must be 43 to 128 characters from the unreserved set: letters, digits, -, ., _, ~. A common bug is generating 32 random bytes and hex-encoding them, which gives 64 valid characters (fine), versus Base64-encoding them with padding, which produces = characters (invalid at strict servers).
  2. The challenge must be Base64url, not Base64. + becomes -, / becomes _, and padding is stripped. Standard Base64 output will verify at zero providers.
  3. The verifier must survive the redirect. You generate the verifier before navigating away and need it back afterwards. sessionStorage works for same-tab redirects but is empty if the provider opens your callback in a new tab, or if the flow started in one browser context and finished in another (common with native-app webviews and with Safari's "open in new window" behavior). A cookie scoped to the callback path survives all of these.

To verify your challenge computation, hash a known verifier and compare. The RFC's own test vector: verifier dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk must produce challenge E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM. You can reproduce this in the browser with the SHA-256 hash tool, remembering the Base64url conversion.

#2state mismatch: usually a storage problem, not an attack

Your app generates a random state, sends it with the authorization request, and verifies the same value comes back. A mismatch in production is rarely CSRF. It is almost always your storage:

  • State saved in sessionStorage, callback opened in a different tab or window. Same failure mode as the PKCE verifier.
  • State cookie set with SameSite=Strict. The redirect back from the provider is a cross-site navigation, so a Strict cookie is not sent on that first request. Use SameSite=Lax, which is sent on top-level navigations.
  • Two login attempts racing: the user clicks "Log in" twice, the second attempt overwrites the stored state, then the first redirect arrives carrying the old value.

Keep the state check strict even though false positives are annoying. Dropping it reopens the CSRF hole that it exists to close.

#2CORS errors at the token endpoint

If a SPA exchanges the code directly from the browser, the token endpoint must send CORS headers for your origin. When it does not, the browser reports a CORS failure even though the underlying request may have succeeded. The error you see in the console is about header visibility, not OAuth. We wrote up the mechanics in the CORS debugging guide.

Two honest options:

  • Providers that support browser-based exchange (Auth0, Okta, Google, and most modern identity platforms) send CORS headers on the token endpoint for registered SPA clients. If you get CORS errors anyway, your client is probably registered with the wrong application type.
  • Providers that do not expect a backend-for-frontend: your server does the exchange, keeps tokens out of the browser entirely, and sets a session cookie. More work, better token hygiene.

#2After the exchange: inspect what you actually got

A successful token response can still be subtly wrong: missing scopes the user declined, an audience claim pointing at the wrong API, an expiry far shorter than you assumed. If the access token is a JWT, decode it and read the claims before writing any retry logic around opaque 401s. The JWT decoder runs locally in the browser, which matters here because pasting production access tokens into a random web service is exactly how tokens leak. For what each claim means, see the JWT guide.

Check three claims first: aud (is this token for the API you are calling?), scope or scp (did you get the scopes you asked for?), and exp (how long do you really have?). A 401 from your API with a syntactically valid token is usually one of those three, not the OAuth flow at all.

#2A quick reference table

ErrorFirst thing to check
redirect_uri_mismatchDiff the sent URI against the registered one, character by character
invalid_grant (code exchange)Code age, code reuse (StrictMode double-fire), PKCE verifier, redirect_uri parity
invalid_grant (refresh)Rotation: was this refresh token already used once?
invalid_clientAuth method (Basic vs body), URL-encoding of the secret, client type
invalid_scopeScope string against the provider's exact published names
access_deniedThe user said no, or an org policy said no for them
state mismatchSameSite on the state cookie, new-tab callbacks, double login clicks
CORS failure on token POSTClient registered as SPA? Provider supports browser exchange at all?

#2Sources / Further reading

Written by Rahul Jalavadiya, founder of AllDevToolsHub. The OAuth debugger, JWT decoder, and hash tools referenced above run in your browser; tokens and secrets you paste never reach our servers.

Quick Summary

OAuth errors are terse on purpose: the spec tells providers not to leak details to an untrusted client. This guide maps each common error (invalid_grant, redirect_uri_mismatch, invalid_client, PKCE failures, state mismatch) back to the specific request parameter that caused it, so you can fix the flow instead of guessing.

RJRahul JalavadiyaFounder & Lead Engineer
Published 2026-11-13Last reviewed 2026-11-13

Tools Mentioned in This Article

Tools, tactics, and toughened-up tips, once a week

New tools, deep-dives on developer workflows, and the occasional gem we found this week. No spam, no tracking. Unsubscribe anytime.

Found an error or have feedback?

We correct errors quickly and document changes in our changelog. Report issues at support@alldevtoolshub.com.

Last reviewed: 2026-11-13
Security Memo
AT

Rahul Jalavadiya

Engineering Protocol V1

Specializing in local-first architecture and Zero-Trust developer workflows. No data leaves the machine.