Fixing JWT Invalid Signature Errors

Fixing JWT Invalid Signature Errors

For invalid signature errors, the message gives little detail but the header gives plenty. JWT verification failures usually come from four causes: wrong secret, algorithm mismatch, token truncation, and multi-tenant key confusion. Each requires a different fix, yet all look identical in the error log. Reading the decoded header (particularly the alg and kid claims) is the fastest first diagnostic step. Paste any token above to see the exact algorithm and key identifier before modifying a single line of verification code.

The decoder above reveals the alg value without verification. If alg: RS256 appears in the header but your server is using an HMAC secret for verification, the algorithm mismatch is immediately visible. Similarly, a missing or unexpected kid tells you whether JWKS key selection is failing. Because signature errors provide no claim data on failure, pre-decoding the header offline gives you the information you need to diagnose without requiring a successful verification round-trip.

Wrong secret or algorithm

The most common cause of invalid signature errors is verifying with the wrong key. For HS256 tokens, the signing and verification secrets must be identical byte sequences: a single character difference produces a completely different HMAC.¹ For RS256 tokens, the verification key must be the correct public key for the private key that signed the token.¹

Reading alg before changing the secret

Algorithm confusion is a related vulnerability: a token signed with RS256 but verified with an HS256 check that uses the public key as the secret will produce a valid HMAC under certain libraries, creating a security flaw rather than an error.² Reading the alg value from the decoded header before touching any verification code tells you exactly which algorithm the issuer intended, which prevents the accidental switch from asymmetric to symmetric verification that enables this attack.

Token mutation

A JWT is invalid the moment a single character changes after signing, because the cryptographic signature covers every byte of the header and payload sections.³ Copy-paste truncation, a trailing newline, a missing equals sign in Base64 padding, or URL encoding that turns + and / into %2B and %2F all produce an altered signature section that verification rejects. Decoding the header and payload in the decoder above confirms whether the content is intact; if the claims look correct but signature verification still fails, the issue is mutation rather than a key mismatch, and whitespace added by email clients or log formatting tools is a common silent truncation source that is easy to overlook.

Multi-tenant key selection

Systems that accept tokens from multiple issuers must select the correct verification key before checking the signature, because verifying an Auth0 token with an Okta JWKS or vice versa always fails even when the token is perfectly valid. The iss claim identifies the issuer while the kid claim identifies the specific key within that issuer's JWKS, so your verification logic should read iss first, resolve the appropriate JWKS endpoint, then select the key by kid.⁴ Never attempt to verify a token before confirming you have the correct issuer's key, because doing so produces invalid signature errors that look like key problems but are actually routing problems caused by selecting the wrong JWKS endpoint.

Systematic debugging steps for invalid signature errors

Systematic debugging starts with the header, not the error message. Paste the failing token into the decoder above and read the alg and kid values before touching verification code. If alg is RS256 but your code supplies a symmetric HMAC secret, the algorithm mismatch is the cause and no secret value will fix it. If alg matches your expected algorithm, note the kid and confirm it appears in the JWKS response from your provider's key endpoint.⁵

Diagnosing key format problems

If the kid is present in the JWKS, the error is likely a key format problem. Log the exact public key bytes your library receives and compare them against the n and e parameters for that kid in the JWKS. A common cause is PEM formatting: an extra newline, a missing header line, or base64 padding stripped incorrectly produces a valid-looking key object that verifies nothing. Reconstruct the key from the JWKS parameters rather than from a file you may have corrupted during copy-paste.

Cross-service mismatches

When a token works in one service but fails in another, compare issuer, audience, and algorithm before comparing key material. A token from a different environment often carries the right format but the wrong iss or aud, and a service that expects HS256 will reject an RS256 token even when the public key is correct. Fix the routing mismatch first, then revisit key formatting only if the header and JWKS agree.

A token that verifies fine in one service but fails in another is usually crossing an environment boundary rather than suffering key damage. Confirming iss and aud line up first saves you from re-importing key material that was never the problem. Once the routing is correct, any remaining failure points squarely at the key format or the signature itself, and running through these steps starting with invalid JWT signature debugging steps to read the header takes seconds and rules out two of the four common causes immediately.

When to use this

Read the decoded token header whenever you encounter an invalid signature error: the alg and kid values diagnose most causes before you write a single line of debug code.

Examples