Common JWT Errors and How to Debug Them
A practical guide to debugging JWT parsing errors — base64 decoding issues, Bearer prefix problems, signature mismatches, and how to fix them.
Why JWT Parsing Fails
JWT parsing errors are some of the most frustrating issues in API development. The error messages are often cryptic — 'illegal base64 data at input byte 0', 'signature is invalid', or 'token contains an invalid number of segments'. Most of these errors have simple causes: including the Bearer prefix in the token string, using the wrong signing key, or passing an expired token. Understanding what each error means saves hours of debugging. Use our JWT Decoder to inspect token parts and spot issues instantly.
The Bearer Prefix Problem
The most common JWT error is passing 'Bearer <token>' instead of just '<token>' to the parser. When you extract the Authorization header, it contains 'Bearer eyJhbGci...'. If you pass this whole string to jwt.ParseWithClaims (Go), jwt.verify (Node.js), or any parser, the library tries to base64-decode 'Bearer ' as the header segment, which fails with 'illegal base64 data at input byte 0'. Always strip the prefix: tokenString = strings.TrimPrefix(tokenString, 'Bearer ') in Go, or token = authHeader.replace('Bearer ', '') in JavaScript. Our JWT Decoder accepts tokens with or without the prefix and shows you the decoded parts.
Signature Validation Errors
'Signature is invalid' or 'token signature does not match' means the token was signed with a different secret or key than what you're using to verify. Common causes: using HS256 (symmetric) signing but passing an RSA public key for verification, rotating the signing secret without accounting for tokens issued under the old secret, or environment mismatch (development vs production secret). For Go's jwt.ParseWithClaims, check that your token's signing method matches the expected method in the callback. The error 'unexpected signing method' fires when the token uses a different algorithm than your code expects. Always verify the algorithm in your parser: if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok { return nil, errors.New('unexpected signing method') }.
Expiration and Claim Validation
'Token is expired' is straightforward — the exp (expiration) claim has passed. But 'invalid claims' or structural errors often mean missing required claims. If your parser expects custom claims (like a UserClaims struct), but the token only contains standard registered claims (iss, sub, exp, iat), parsing fails. Always log the raw error from the parser. For Go: _, err := jwt.ParseWithClaims(...) — the err contains the specific failure reason. Validate all standard claims: iss (issuer) should match your auth server URL, aud (audience) should match your service name, exp must be in the future. Our JWT Expiration Checker decodes and displays all claims so you can verify expiration and payload structure at a glance.
Multi-Secret Key Rotation Strategy
When rotating JWT signing keys, tokens issued under the old key will fail validation after rotation. The solution: maintain a list of valid keys and try each one. In Go, collect all valid secrets in a slice and attempt parsing with each. In the jwt.ParseWithClaims key function, iterate over keys and return the first one that matches the token's key ID (kid header). Include a grace period where both old and new keys are accepted. Store the kid in the JWT header so your parser can select the correct key without trying all possibilities. Use our JWT Decoder to inspect the kid header and verify which key was used to sign. This pattern lets you rotate keys without invalidating existing sessions.
Use our free online tool to get started instantly.