ruvnet/RuView · error · HTTPException

JWT authentication is not configured. In development mode…

Error message

JWT authentication is not configured. In development mode, either disable authentication (enable_authentication=False) or configure JWT validation. Returning mock users is not permitted in any environment.

What it means

FastAPI dependency get_current_user raises 401 with this message when the request carries Authorization credentials, settings.is_development is true, but JWT validation is not configured (JWT_SECRET/JWT_ALGORITHM unset). The code deliberately refuses to return mock users in any environment, so dev mode with credentials present but no JWT setup is rejected.

Solutions

For pure local development, set enable_authentication=False so credentials are not required at all
Or configure JWT_SECRET and JWT_ALGORITHM environment variables for the dev server and restart it
Clear the stale bearer token the client is sending (logout / clear local storage)
Follow docs/authentication.md referenced by the sibling production message

Example fix

# before: dev server with auth enabled but no secrets
# enable_authentication=True, JWT_SECRET unset -> 401

# after (option A): disable auth in dev
export ENABLE_AUTHENTICATION=false

# after (option B): configure JWT
export JWT_SECRET=$(openssl rand -hex 32)
export JWT_ALGORITHM=HS256

Defensive patterns

Strategy: validation

Validate before calling

# Fail fast at startup instead of per-request 401s
from src.api.dependencies import get_settings
s = get_settings()
if s.enable_authentication and not s.is_development and not (s.jwt_secret and s.jwt_algorithm):
    raise RuntimeError('JWT_SECRET/JWT_ALGORITHM required when authentication is enabled')

Try / catch

try:
    resp = client.get('/api/protected', headers={'Authorization': f'Bearer {token}'})
except httpx.HTTPStatusError as e:
    if e.response.status_code == 401 and 'JWT authentication is not configured' in e.response.text:
        # dev environment misconfiguration: fix server env, not the token
        raise SystemExit('Configure JWT_SECRET or set enable_authentication=False')
    raise

Prevention

Keep a checked-in dev .env.example with JWT_SECRET/JWT_ALGORITHM placeholders
Clear stored bearer tokens when switching environments
Prefer enable_authentication=False for local work that does not exercise auth paths

When it happens

Trigger: Dev server started with authentication enabled and JWT_SECRET unset while the client sends an Authorization: Bearer header; a browser or API client replaying a token saved from another environment against a fresh dev setup.

Common situations: Copying a .env template without filling the JWT secrets; frontend auto-attaching a stale token; flipping enable_authentication to true in dev without completing JWT configuration.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of ruvnet/RuView@4685618388 (2026-08-16). Data as JSON: /api/errors/8750cde7028b7f25. Report an issue: GitHub.

Appendix: source

Thrown at archive/v1/src/api/dependencies.py:90

    
    # Check if user is already set by middleware
    if hasattr(request.state, 'user') and request.state.user:
        return request.state.user
    
    # No credentials provided
    if not credentials:
        return None
    
    # Validate the JWT token
    # JWT validation must be configured via settings (e.g. JWT_SECRET, JWT_ALGORITHM)
    if settings.is_development:
        logger.warning(
            "Authentication credentials provided in development mode but JWT "
            "validation is not configured. Set up JWT authentication via "
            "environment variables (JWT_SECRET, JWT_ALGORITHM) or disable "
            "authentication. Rejecting request."
        )
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail=(
                "JWT authentication is not configured. In development mode, either "
                "disable authentication (enable_authentication=False) or configure "
                "JWT validation. Returning mock users is not permitted in any environment."
            ),
            headers={"WWW-Authenticate": "Bearer"},
        )

    # In production, implement proper JWT validation
    raise HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail=(
            "JWT authentication is not configured. Configure JWT_SECRET and "
            "JWT_ALGORITHM environment variables, or integrate an external "
            "identity provider. See docs/authentication.md for setup instructions."
        ),
        headers={"WWW-Authenticate": "Bearer"},

View on GitHub (pinned to 4685618388)