How to Debug JWT Errors: Fix Invalid, Expired & Signature Issues (Complete Guide)

Introduction

JSON Web Tokens (JWT) are widely used for authentication in modern web applications. However, developers often face frustrating issues such as invalid tokens, expired tokens, or signature verification failures.

If you've ever seen errors like:

"Invalid token"
"jwt malformed"
"jwt expired"
"signature verification failed"

You're not alone.

In this guide, we will walk through how to debug JWT errors step-by-step, understand the root causes, and fix them using practical examples.

👉 You can also instantly inspect and debug your token using our tool: https://www.mydevtoolhub.com/tools/jwt-decoder

What is a JWT (Quick Recap)

A JWT consists of three parts:

Code

Header.Payload.Signature

Example:

Code

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.
eyJ1c2VySWQiOiIxMjMiLCJleHAiOjE3MDAwMDAwMDB9
.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Each part is Base64 encoded and can be decoded to understand the token.

Common JWT Errors and How to Fix Them

1. "jwt malformed" Error

Cause:

Token is not in correct format
Missing parts (header, payload, signature)

Example Problem:

Code

abc.def

Fix:

Ensure token has 3 parts separated by dots
Validate token before using it

Code

if (!token || token.split('.').length !== 3) {
  throw new Error('Invalid JWT format');
}

2. "Invalid Token" Error

Cause:

Token is corrupted
Improper encoding

Debug Tip:

Paste your token into: https://www.mydevtoolhub.com/tools/jwt-decoder

Check if:

Header and payload are readable
JSON structure is valid

3. "jwt expired" Error

Cause:

Token has expired based on exp field

Example Payload:

Code

{
  "userId": "123",
  "exp": 1700000000
}

Fix:

Refresh token
Increase expiry time (if appropriate)

Code

jwt.sign(payload, secret, { expiresIn: '1h' });

Pro Tip:

Always implement refresh tokens for better UX.

4. "Invalid Signature" Error

Cause:

Secret key mismatch
Token tampered

Fix:

Ensure the same secret is used:

Code

jwt.verify(token, process.env.JWT_SECRET);

If using multiple environments:

Check .env consistency
Avoid hardcoding secrets

5. "jwt not active" Error

Cause:

Token used before nbf (Not Before)

Example:

Code

{
  "nbf": 1700000000
}

Fix:

Ensure server time is correct
Avoid future timestamps

Step-by-Step JWT Debugging Process

Follow this workflow whenever you face JWT issues:

Step 1: Validate Format

Check if token has 3 parts

Step 2: Decode Token

Use: https://www.mydevtoolhub.com/tools/jwt-decoder

Analyze:

Payload data
Expiration (exp)
Not before (nbf)

Step 3: Verify Signature

Confirm secret key
Match algorithm (HS256, RS256)

Step 4: Check Expiry

Compare exp with current timestamp

Step 5: Validate Environment

Same secret across backend
Correct timezone

Debugging JWT in Node.js (Practical Example)

Code

const jwt = require('jsonwebtoken');

try {
  const decoded = jwt.verify(token, process.env.JWT_SECRET);
  console.log(decoded);
} catch (err) {
  if (err.name === 'TokenExpiredError') {
    console.log('Token expired');
  } else if (err.name === 'JsonWebTokenError') {
    console.log('Invalid token');
  } else {
    console.log('Other error:', err.message);
  }
}