Troubleshooting

Common issues and their solutions when using Application Kit.

Authentication Issues

"Authentication service unavailable"

Symptoms: Requests fail with connection errors to the authentication service.

Causes:

• Authentication service URL not configured
• Network connectivity issues
• Authentication service is down

Solutions:

1. Verify the authentication service is declared in your application.json:

   {
     "dependencies": {
       "services": [
         {"name": "authentication", "test_value": "http://localhost:34555"}
       ]
     }
   }
   

2. Check that the authentication service is running and accessible

3. Verify network/firewall settings allow connections

"Token validation failed"

Symptoms: Valid-looking API keys are rejected.

Causes:

• Token has expired
• Token was revoked
• Wrong token type for the endpoint
• Cache contains stale data

Solutions:

1. Verify the token is valid in the Woosmap console
2. Check token type matches endpoint requirements (public vs private key)
3. Clear the authentication cache in Redis if using cached validation

"Permission denied"

Symptoms: Authenticated requests fail with 403 errors.

Causes:

• Token doesn't have required permissions
• Using wrong permission class
• Origin not allowed for public keys

Solutions:

1. Check the permission classes on your endpoint
2. For public keys, verify the request origin matches allowed domains
3. For private keys, verify the key has the required permissions (read/write)

Rate Limiting Issues

Rate limits not working

Symptoms: Requests are not being rate limited despite configuration.

Causes:

• Redis dependency not configured
• Rate limit decorator placed before authentication
• Redis connection failing silently

Solutions:

1. Verify ratelimit Redis is declared in application.json:

   {
     "dependencies": {
       "databases": [
         {"name": "ratelimit", "type": "redis"}
       ]
     }
   }
   

2. Ensure @rate_limit comes after @authenticate_key:

   @authenticate_key()  # First
   @rate_limit(max_requests=100, expiry=60)  # Second
   def my_view(request):
       ...
   

3. Check Redis connectivity

Rate limit overrides not applying

Symptoms: Custom rate limits per project are ignored.

Causes:

• Override key format mismatch
• Override expired
• Override set on wrong Redis instance

Solutions:

1. Verify override key format: ratelimit_override:{endpoint}:{org_id}:{project_id}
2. Check if override has a TTL that expired
3. Ensure overrides are set on the same Redis instance used for rate limiting

Redis Issues

"Redis connection refused"

Symptoms: Operations fail with connection errors.

Causes:

• Redis not running
• Wrong host/port configuration
• Network/firewall blocking connection

Solutions:

1. Verify Redis is running: redis-cli ping
2. Check your Bender manifest database configuration
3. Verify network connectivity to Redis host

"Redis timeout"

Symptoms: Requests hang or timeout when accessing Redis.

Causes:

• Redis overloaded
• Network latency
• Connection pool exhausted

Solutions:

1. Check Redis performance metrics
2. Consider increasing connection pool size
3. Review rate limiting expiry times (shorter windows = more Redis operations)

Metrics Issues

Metrics not being recorded

Symptoms: count_request decorator not sending metrics.

Causes:

• metrics_queue Redis not configured
• Queue worker not processing jobs
• Decorator not applied correctly

Solutions:

1. Verify metrics_queue is declared in application.json:

   {
     "dependencies": {
       "databases": [
         {"name": "metrics_queue", "type": "redis", "extras": {"queue_prefix": "counter"}}
       ]
     }
   }
   

2. Ensure the metrics queue worker is running

3. Verify decorator order (usually after authentication)

Framework-Specific Issues

Django: "project_token not found on request"

Symptoms: AttributeError when accessing request.project_token.

Causes:

• Authentication decorator not applied
• Decorator order incorrect
• Request bypassed authentication

Solutions:

1. Add @authenticate_key() or @authenticate_user() decorator
2. Ensure authentication decorator is the outermost decorator
3. Use get_project_token(request) for safer access with error handling

FastAPI: Dependency injection not working

Symptoms: Security dependencies not receiving correct values.

Causes:

• Not using Depends() correctly
• Missing app configuration
• Wrong import path

Solutions:

1. Verify dependency usage:

   from fastapi import Depends
   from application_kit.fastapi.security import AuthenticateKey
   
   @app.get("/endpoint")
   async def my_endpoint(auth: AuthenticateKey = Depends()):
       ...
   

2. Ensure you're using get_fastapi_app() or properly configured app

Django Ninja: Chain/Terminate decorators not working

Symptoms: Decorators don't execute or execute in wrong order.

Causes:

• Missing @terminate() decorator
• Wrong decorator order
• Not using @chain() wrapper

Solutions:

1. Always end with @terminate():

   @api.get("/endpoint", auth=[PublicKeyAuth()])
   @chain(authenticate_key(), count_request("endpoint", "SERVICE"))
   @terminate()
   def my_endpoint(request):
       ...
   

Configuration Issues

"Manifest not found"

Symptoms: Application fails to start with configuration errors.

Causes:

• application.json not in expected location
• Bender not properly initialized
• Environment variables not set

Solutions:

1. Verify application.json exists in your project root
2. Check Bender environment configuration
3. For local development, ensure test values are set in manifest

Settings not loading

Symptoms: get_configuration() or get_redis_instance() returns None or raises errors.

Causes:

• Dependency not declared in manifest
• Typo in dependency name
• Bender not initialized

Solutions:

1. Verify dependency names match exactly between code and manifest
2. Check for typos in application.json
3. Ensure Bender is initialized before accessing settings