Keycloak invalid_grant: the eight things it actually means
· 12 min read
Keycloak returns invalid_grant for at least eight unrelated failures, and the error code
itself tells you nothing. The useful field is error_description, which Keycloak fills in
with a short string that maps almost one-to-one onto a cause:
{"error":"invalid_grant","error_description":"Code not valid"}
invalid_grant is OAuth's designated bucket for "the grant you presented is no good", so
Keycloak uses it for expired codes, replayed codes, PKCE mismatches, rotated refresh tokens,
dead sessions, revoked offline tokens, and bad passwords alike. Read the description, find
it in the table below, stop guessing.
Everything here was run against Keycloak 26.7.3 on 2026-09-07, with realm defaults except where a test says otherwise.