Why Your JWT Isn't Working: A Debugging Checklist

A JWT-based login stops working, or a request that should be authenticated comes back 401 Unauthorized, and the error message is unhelpfully generic. This is one of the more frustrating categories of bug precisely because the token itself often looks fine when you glance at it. Here's a systematic way to actually find the cause, instead of guessing.

Step 1: decode the token and actually look at it

Before anything else, decode the token and read what's actually inside it. A JWT Decoder splits the token into its header and payload and shows you the real, decoded JSON — not what you assume is in there. This step alone catches a surprising number of bugs: a token from the wrong environment, a payload missing a claim your code expects, or a token that's technically well-formed but simply isn't the one you thought you were testing with.

Step 2: check the expiration claim

The exp claim is a Unix timestamp marking when the token expires. This is the single most common reason a previously-working token suddenly stops authenticating — it simply timed out. A few things to check specifically:

• Is exp actually in the future, relative to the current time, in seconds (not milliseconds)? A surprisingly common bug is a token generator that sets exp in milliseconds instead of seconds, which either creates a token that expires almost instantly or one that appears to expire thousands of years in the future — both wrong, for different reasons.
• Is the server's clock correct? JWT expiration checks compare against server time. A server with a wrong system clock will reject valid, non-expired tokens or accept ones that should have expired. This is rare but real, especially on containers or VMs with clock drift.
• Is there a nbf (not before) claim that hasn't been reached yet? Less common than exp, but a token with a future nbf will be rejected as "not yet valid," which produces a similar-looking failure to expiration.

Step 3: verify the algorithm matches on both ends

The JWT header specifies which algorithm was used to sign the token (commonly HS256 or RS256). If the issuing service signs with one algorithm and the verifying service is configured to expect a different one, verification fails — and the error is often a generic "invalid signature" that doesn't hint at the actual mismatch. This is especially easy to get wrong when switching a system from symmetric signing (HS256, one shared secret) to asymmetric signing (RS256, a public/private key pair) and not updating every service that verifies tokens.

Step 4: confirm you're checking the right secret or key

For HS256 tokens, both the signing side and verifying side need the exact same secret string. A trailing space, a secret loaded from the wrong environment variable, or a secret that got rotated on one service but not the other will all produce a token that decodes fine (remember: decoding doesn't require the secret) but fails signature verification.

For RS256 tokens, confirm the verifying service actually has the current public key — this bites teams especially after a key rotation, when old services keep the previous public key cached and reject tokens signed with the new private key.

Step 5: check for a stripped or mangled "Bearer " prefix

Tokens are typically sent in an Authorization header formatted as Bearer <token>. If your code passes the entire header value (including "Bearer ") into a JWT verification function that expects just the token, verification fails — not because the token is invalid, but because the "Bearer " prefix and space are still stuck to the front of the string. This is a common, easy-to-miss bug, especially after refactoring how a header gets parsed.

Step 6: rule out a decoded-but-unverified token being trusted incorrectly

This one is a security bug, not just a functional one, and it's worth explicitly checking your code for: decoding a JWT is not the same as verifying it. Reading the payload out of a token (to display a username, for example) doesn't confirm the token's signature is valid. If any code path decodes a token and trusts its contents without going through a proper signature verification step first, that's a real vulnerability, not just a debugging inconvenience — an attacker could hand-craft a token with any payload they want, since the payload segment is only Base64URL-encoded, not encrypted or otherwise protected on its own.

A fast checklist for next time

When a JWT issue comes up again, work through this in order — it resolves the large majority of real cases:

1. Decode it and confirm the payload actually contains what you expect
2. Check exp against the current time, in the right unit (seconds)
3. Confirm the signing and verifying algorithms match
4. Confirm the secret or public key is current on the verifying side
5. Confirm the raw token (not the full Authorization header value) is what's being passed to verification
6. Confirm nothing trusts a decoded-but-unverified payload as authenticated