JWT Token Debugging: Common Issues

Why JWTs break and where to look

JWT-based authentication fails in a handful of recurring ways: expired tokens, clock skew, mismatched issuer or audience, algorithm confusion, and signature verification errors.

Nearly all of them leave a readable trace. A JWT is not opaque - its header and payload are Base64URL-encoded JSON that anyone can decode. The claims tell you what the token claims about itself; your server's error tells you what it rejected.

This guide walks the debugging workflow from the token itself to the library configuration, and shows how to do it without leaking the token to a random website.

JWT anatomy: three segments, one signature

A JWT is three dot-separated segments: header.payload.signature.

The header declares the algorithm (alg) and token type (typ). The payload contains claims - statements about the subject and the token itself. Both are plain JSON, encoded with Base64URL, readable by anyone.

The signature is produced with the algorithm from the header and a key held by the issuer. It lets a verifier confirm the token was not modified and was signed by the expected party.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
# header      = {"alg":"HS256","typ":"JWT"}
# payload     = {"sub":"1234567890","name":"John Doe","iat":1516239022}
# signature   = HMAC-SHA256(header.payload, secret)

The standard claims and what they mean

A safe debugging workflow

1. Copy the full JWT from the log, header, or failing request - both dots included.
2. Decode it locally with the JWT Decoder - never paste production tokens into an unverified online service.
3. Read the payload claims: exp, iat, nbf, iss, aud, sub.
4. Convert exp to a human-readable time and compare it with the server's current time, not your laptop's.
5. Check iss and aud against what your API is configured to accept.
6. If the claims look correct, the failure is in verification: algorithm, key, or clock handling in the library.
7. Redact the token before sharing logs with anyone, even internally.

Common failure patterns and fixes

Decoding is not verifying

Decoding reads the claims - any tool can do it, no key required. Verifying proves the token is authentic: signature, exp, nbf, iss, aud, and algorithm, checked by the server with the correct key.

Debugging usually starts with decoding to understand the token, then moves to verification to understand why the server rejected it.

Be careful with decoder services that claim to verify signatures: real verification requires the signing secret or public key, which a remote service should never ask you to provide. A client-side tool is the safe default.

Debugging tools beyond the decoder

• A client-side JWT decoder for reading claims without uploading the token
• The Timestamp Converter for turning exp/iat Unix seconds into readable dates
• A Base64/Base64URL decoder for inspecting individual segments
• Your language's JWT library with signature verification enabled and the algorithm pinned
• Structured request logging that masks Authorization headers by default

FAQ

References

• RFC 7519 – JSON Web Token (JWT): https://www.rfc-editor.org/rfc/rfc7519
• RFC 7515 – JSON Web Signature (JWS): https://www.rfc-editor.org/rfc/rfc7515
• RFC 7517 – JSON Web Key (JWK): https://www.rfc-editor.org/rfc/rfc7517
• OWASP JWT Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html