How to Fix "JWT Expired" and "Invalid Signature" Errors

JWT errors like TokenExpiredError, JsonWebTokenError, and invalid signature are the most common authentication debugging issues in web development. This guide explains every major JWT error, its specific cause, and how to fix it without exposing your tokens to third-party tools.

Table of Contents

1. The 5 Most Common JWT Errors
2. How to Debug a JWT Without Exposing It
3. JWT Expiration — How Token Lifetime Works
4. How to Prevent JWT Errors in Production
5. FAQ

The 5 Most Common JWT Errors

Understanding the root cause of automated error messages is the first step toward a secure resolution. Below are the five most frequent issues developers encounter when working with JSON Web Tokens.

1. TokenExpiredError: jwt expired

• Cause: The exp (expiration) claim in the token's payload contains a timestamp that is now in the past. The server correctly rejects the token as it is no longer valid.
• Fix:
  • Sync Server Clocks: Ensure your application servers and authentication servers are using synchronized NTP clocks. Even a few seconds of drift can cause immediate expiration.
  • Increase Token Lifetime: Adjust the expiresIn setting during token signing (e.g., from 15m to 30m) if the window is too narrow for user activity.
  • Refresh Tokens: Implement a refresh token pattern to allow users to obtain a new access token seamlessly without re-logging.

2. JsonWebTokenError: invalid signature

• Cause: The cryptographic signature at the end of the JWT does not match the content of the header and payload when verified with the provided secret or public key.
• Fix:
  • Match Keys: Ensure the secretOrPublicKey used in your verification function matches exactly what was used for signing.
  • Check Algorithm Confusion: A dangerous vulnerability where a hacker changes the algorithm from RS256 to HS256. Read our deep dive on JWT Algorithm Confusion Security.

3. JsonWebTokenError: jwt malformed

• Cause: The token string does not follow the standard header.payload.signature format. It might be missing a period, contain non-Base64 characters, or be accidentally truncated.
• Fix:
  • Check for extra whitespace or newlines in the string.
  • If sending via the Authorization: Bearer <token> header, ensure the "Bearer" prefix is correctly stripped before passing the token to your library.

4. JsonWebTokenError: jwt not active (NotBeforeError)

• Cause: The nbf (not before) claim timestamp is in the future. The token was issued but isn't allowed to be used yet.
• Fix:
  • Check server clock synchronization.
  • If intentional (e.g., a scheduled access token), wait for the designated start time.

5. Error: invalid algorithm

• Cause: The algorithm specified in the JWT header (e.g., none or HS256) is not in the list of algorithms the server is configured to accept.
• Fix:
  • Explicitly set the algorithms array in your verification code (e.g., jwt.verify(token, key, { algorithms: ['RS256'] })). This prevents "Algorithm Downgrade" attacks.

How to Debug a JWT Without Exposing It

One of the most common mistakes developers make is pasting a production JWT into a public online decoder to see why it's failing.

The Risk: Most online decoders are marketing frontends for SaaS companies. When you paste your token, it is sent to their server. If that token is still valid, the tool provider (or anyone with access to their logs) can compromise your user sessions or administrative accounts.

The Solution: Local Browser Decoding

FmtDev provides a 100% Client-Side solution. Our tools run entirely in your browser's memory using JavaScript; your token never leaves your machine.

1. Copy your problematic JWT.
2. Navigate to our Local JWT Decoder.
3. Paste the token to instantly see the decoded Header and Payload.
4. Check the exp, iat, and nbf claims specifically—they are the most common culprits for "Expired" or "Not Active" errors.

JWT Expiration — How Token Lifetime Works

JWTs are "stateless," meaning the server doesn't need to look up a session in a database. Everything it needs to know is inside the token.

• exp (Expiration Time): The Unix timestamp when the token must stop being accepted.
• iat (Issued At): When the token was originally generated.
• nbf (Not Before): The earliest possible time the token can be used.

Calculating Lifetime

You can calculate the remaining time by subtracting the current Unix timestamp (in seconds) from the exp value.

// Node.js example using jsonwebtoken
const jwt = require('jsonwebtoken');

try {
  const decoded = jwt.verify(token, 'your-secret');
} catch (err) {
  if (err.name === 'TokenExpiredError') {
    const expiredAt = err.expiredAt;
    console.error(`Token expired at: ${expiredAt}`);
  }
}

Common Mistake: Lifetime Management

• Too Short: 1 minute. Users will experience constant 401 errors if the refresh logic isn't perfect.
• Too Long: 1 year. If a token is stolen, the attacker has access for the entire year unless you implement a complex blacklist/revocation system.

How to Prevent JWT Errors in Production

Prevention is better than debugging. Follow these industry standards to minimize JWT issues:

1. Explicit Verification: Always pass the expected algorithm to the verify function. Never rely on the token header's suggestion.
2. Use Asymmetric Keys: For larger systems, sign tokens with a private key (RS256) and verify them using a public key. This allows different microservices to verify tokens without knowing the secret signing key.
3. Refresh Token Rotation: Issued short-lived access tokens (15 mins) and long-lived refresh tokens (7 days). Rotate the refresh token every time it is used to detect potential theft.
4. Handle Clock Skew: Many libraries allow a clockTolerance (e.g., 30 seconds) to account for minor time differences between servers.
5. Payload Privacy: Never put passwords, API keys, or PII in a JWT. It is encoded, not encrypted.

For a deeper dive into security, see our related post on Safe JWT Decoding Locally.

FAQ

Why does my JWT say "invalid signature"?

The most common cause is using the wrong secret key or public key for verification. Make sure the key used to verify matches exactly the key used to sign the token. Also, check that you aren't accidentally trying to verify an RS256 token with a HMAC secret.

How long should a JWT access token last?

For API access tokens, 15-30 minutes is standard. Use refresh tokens to get new access tokens without requiring the user to log in again. This limits the "blast radius" if a token is leaked.

Can I decode a JWT without the secret key?

Yes. The header and payload of a JWT are Base64 encoded, not encrypted. Anyone can decode and read them. The secret key is only needed to verify the signature to prove the token hasn't been tampered with.

Is it safe to paste my JWT into an online decoder?

No. Online decoders send your token to their server where it can be logged. Use a local decoder like FmtDev's JWT Decoder that runs in your browser with zero server calls.

Conclusion

Understanding "JWT Expired" and "Invalid Signature" errors is a rite of passage for modern developers. By implementing proper clock sync, explicit algorithm verification, and using local debugging tools, you can ensure your authentication flow is both robust and secure.

👉 Debug your JWT tokens locally and securely with FmtDev