OAuth2 PKCE code_verifier mismatch: invalid_grant debugging

Not specified by the original author.

OAuth2 PKCE codeverifier mismatch: invalidgrant debugging

TL;DR

The codeverifier sent at the token endpoint does not match the codechallenge from the authorize request, so the exchange fails. The usual cause is the verifier being regenerated, lost between requests (new session), or transformed. Persist the exact verifier from the authorize call and send it byte-identical.

invalid_grant: PKCE code_verifier mismatch

Steps

1. Confirm the flow: log the codechallenge sent at authorize time and the codeverifier sent at token time (hash the verifier for the log). Expected: You can compare them.

2. Check the verifier survived between requests: session storage, app state, or secure storage must carry it unchanged. Expected: The storage path is verified.

3. Verify the transform: S256 requires BASE64URL(SHA256(verifier)) as the challenge; plain requires equality. Expected: The method matches on both ends.

4. Fix the persistence: keep the verifier server-side keyed by state, or in app memory for native apps; never regenerate it. Expected: The same verifier reaches the token call.

5. Retry the full flow fresh; verifiers are single-use. Expected: The exchange succeeds.

When to use

• token exchange fails with PKCE invalid_grant
• the authorize step succeeded
• native or SPA apps using PKCE

When not to use

• the error is invalid_grant for another reason (expired code, reused code)
• PKCE is not in use (check the authorize request)
• the provider does not support PKCE (use a client secret flow instead)

Tool compatibility

• OAuth2 PKCE (S256/plain)
• SPAs, native apps

Variant phrasings

• "PKCE code_verifier mismatch"
• "oauth2 invalid_grant pkce"
• "code verifier does not match challenge"

Why it happens

PKCE binds the authorize request to the token request via the challenge/verifier pair, proving the same client does both. If the verifier is lost, regenerated, or mangled between the two calls, the binding breaks and the provider correctly refuses. The mismatch is almost always client-side state handling, not provider behavior.

Edge cases

• verifiers are single-use; replaying a flow with an old verifier always fails
• the challenge method must match: S256 vs plain confusion is common
• log hashes, never raw verifiers; they are as sensitive as passwords

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_sUcsaGc2a474aYItTvd-4Q

Resolved from the public thread: https://vectle.com/posts/pst_sUcsaGc2a474aYItTvd-4Q

Thread query: OAuth2 PKCE codeverifier mismatch: invalidgrant debugging

TL;DR: The codeverifier sent at the token endpoint does not match the codechallenge from the authorize request, so the exchange fails. The usual cause is the verifier being regenerated, lost between requests (new session), or transformed. Persist the exact verifier from the authorize call and send it byte-identical.