Fix ExpiredSignatureError: Signature has expired in Flask

This error occurs when a JWT token presented to your Flask app has passed its expiration time. It typically means the client is using a stale token or the server's expiry window is too short. Fix it by implementing a token refresh endpoint, extending the token lifetime, or catching the exception and returning a proper 401 response.

Reading the Stack Trace

Here's what each line means:

• File "/app/app/auth/decorators.py", line 22, in decorated_function: Your custom decorator calls jwt.decode which validates the token's expiration claim automatically.
• File "/app/venv/lib/python3.12/site-packages/jwt/api_jwt.py", line 281, in _validate_exp: PyJWT's internal validation compares the 'exp' claim to the current UTC time and finds the token is past its expiry.
• jwt.exceptions.ExpiredSignatureError: Signature has expired: The exception propagates up because the decorator has no try-except block to handle expired tokens gracefully.

Common Causes

token = jwt.encode(
    {'user_id': user.id, 'exp': datetime.utcnow() + timedelta(minutes=5)},
    app.config['SECRET_KEY'],
    algorithm='HS256'
)

@app.route('/login', methods=['POST'])
def login():
    user = authenticate(request.json)
    token = create_access_token(user)
    return jsonify({'token': token})  # no refresh token

def token_required(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        token = request.headers.get('Authorization', '').replace('Bearer ', '')
        payload = jwt.decode(token, current_app.config['SECRET_KEY'], algorithms=['HS256'])
        # no try/except — crashes on expired token
        return f(payload, *args, **kwargs)
    return decorated

The Fix

Wrap jwt.decode in a try-except to catch ExpiredSignatureError and InvalidTokenError. Return a structured 401 JSON response with a 'TOKEN_EXPIRED' code so the client knows to call the refresh endpoint instead of crashing with a 500.

def token_required(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        token = request.headers.get('Authorization', '').replace('Bearer ', '')
        payload = jwt.decode(token, current_app.config['SECRET_KEY'], algorithms=['HS256'])
        return f(payload, *args, **kwargs)
    return decorated

def token_required(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        token = request.headers.get('Authorization', '').replace('Bearer ', '')
        if not token:
            return jsonify({'error': 'Token is missing'}), 401
        try:
            payload = jwt.decode(token, current_app.config['SECRET_KEY'], algorithms=['HS256'])
        except jwt.ExpiredSignatureError:
            return jsonify({'error': 'Token has expired', 'code': 'TOKEN_EXPIRED'}), 401
        except jwt.InvalidTokenError:
            return jsonify({'error': 'Token is invalid'}), 401
        return f(payload, *args, **kwargs)
    return decorated

Testing the Fix

import pytest
import jwt
from datetime import datetime, timedelta
from app import create_app

@pytest.fixture
def app():
    app = create_app()
    app.config['TESTING'] = True
    app.config['SECRET_KEY'] = 'test-secret'
    return app

def make_token(app, expired=False):
    exp = datetime.utcnow() + (timedelta(seconds=-10) if expired else timedelta(hours=1))
    return jwt.encode({'user_id': 1, 'exp': exp}, app.config['SECRET_KEY'], algorithm='HS256')

def test_expired_token_returns_401(app):
    client = app.test_client()
    token = make_token(app, expired=True)
    resp = client.get('/api/profile', headers={'Authorization': f'Bearer {token}'})
    assert resp.status_code == 401
    assert resp.get_json()['code'] == 'TOKEN_EXPIRED'

def test_valid_token_succeeds(app):
    client = app.test_client()
    token = make_token(app, expired=False)
    resp = client.get('/api/profile', headers={'Authorization': f'Bearer {token}'})
    assert resp.status_code == 200

def test_missing_token_returns_401(app):
    client = app.test_client()
    resp = client.get('/api/profile')
    assert resp.status_code == 401

Run your tests:

pytest tests/ -v

Pushing Through CI/CD

git checkout -b fix/flask-jwt-expired-token-handling,git add app/auth/decorators.py tests/test_auth.py,git commit -m "fix: handle expired JWT tokens with proper 401 response",git push origin fix/flask-jwt-expired-token-handling

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest tests/ -v --tb=short
      - run: flake8 app/

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

pip install bugstack

import bugstack

bugstack.init(api_key=os.environ["BUGSTACK_API_KEY"])

Deploying the Fix (Manual Path)

1. Run pytest locally to verify all token scenarios return the correct status codes.
2. Open a pull request with the decorator and test changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify expired tokens return 401 in staging.

Frequently Asked Questions