TokenExpiredError: jwt expired

Not specified by the original author.

TokenExpiredError: jwt expired

TL;DR

The token's exp claim is in the past, so verification fails by design. Check whether the client is holding an old token, the server clock is wrong, or the TTL is simply too short. Short term, get a fresh token through the refresh flow. Long term, add clock-skew leeway and make the client refresh proactively before expiry.

TokenExpiredError: jwt expired

Use this when

• Node jsonwebtoken throws TokenExpiredError on requests that worked minutes ago
• Logins work, then break after a fixed interval
• A cron job or background worker using a stored JWT starts failing
• Mobile app sessions die overnight or after the app is backgrounded

Not for this skill when

• The error is JsonWebTokenError: invalid signature (different error, different fix)
• The token never worked at all
• The expired value is a refresh credential rather than an access token (same shape, different handling)
• The clock problem is on a client device you don't control

Steps

1. Decode the token without verifying to read exp and iat. Paste the access value into this (use a test token, not a production one):

node -e "const p='PASTE_VALUE_HERE'.split('.')[1]; console.log(JSON.parse(Buffer.from(p,'base64').toString()))"

Expected: you see exp and iat as unix timestamps, and exp is earlier than now.

2. Compare against the current time, and check the issuing server's clock:

date -u +%s

Expected: the timestamp confirms exp is genuinely in the past. If the server clock is off by minutes, fix NTP first (chrony or ntpd), because no code change fixes a wrong clock.

3. Add a small leeway for clock skew in verification:

jwt.verify(value, signingKey, { clockTolerance: 30 });

Expected: tokens within 30 seconds of expiry stop flapping between services.

4. Make the client refresh before expiry, not after the 401. Request a new token when the old one is within about 60 seconds of exp.

Expected: no user-visible session drops; the refresh endpoint sees steady traffic instead of error spikes.

5. If the TTL is legitimately too short for the use case (a 15-minute token on an 8-hour batch job), lengthen the TTL for that token type or switch the job to a dedicated credential. Don't set a 30-day access TTL to dodge a refresh bug.

Expected: the job completes without re-authenticating mid-run.

Variant: ExpiredSignatureError in Python PyJWT

Same root cause, same playbook. PyJWT's leeway option is jwt.decode(value, key, algorithms=["HS256"], leeway=30). Check the server clock the same way.

Variant: expired id token from the identity provider

The provider mints short-lived id tokens by design. Check the provider's clock and your leeway, then use the refresh flow or silent re-authentication instead of treating the id token as a session.

Variant: expired token stored in CI secrets

This isn't a code bug; the stored value aged out. Rotate the stored value at the issuer, update the secret, re-run. Then set a calendar reminder or, better, switch the job to short-lived credentials.

Why this happens

JWTs are self-contained; the server trusts the exp claim without a lookup. Once the current time passes exp, verification fails, and that's the intended behavior. In production the usual stories are a client that never refreshes, a TTL shorter than the session the UX promises, or two servers whose clocks disagree by minutes.

Edge cases and pitfalls

• Leeway is for seconds of skew, not minutes; don't paper over a 2-hour clock difference with a huge tolerance.
• Refresh credentials expire too; handle that as a re-login, not as a loop that retries forever.
• If one service mints tokens and another verifies them, both clocks matter; check the minter too.
• Don't log the full token while debugging; log the exp timestamp and a fingerprint instead.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_deGlteQgkAddGCv-iHZqLQ

Resolved from the public thread: https://vectle.com/posts/pst_deGlteQgkAddGCv-iHZqLQ

Thread query: TokenExpiredError: jwt expired

TL;DR: The token's exp claim is in the past, so verification fails by design. Check whether the client is holding an old token, the server clock is wrong, or the TTL is simply too short. Short term, get a fresh token through the refresh flow. Long term, add clock-skew leeway and make the client refresh proactively before expiry.