Troubleshooting

Common issues and solutions when working with Phlow.

Authentication Issues

"Invalid JWT token" Error

Symptoms:

AuthenticationError: Invalid JWT token

Common Causes:

Clock Skew: JWT tokens have timestamps that must be within acceptable time windows

# Check system time is correct
date
# Sync system clock if needed
sudo ntpdate -s time.nist.gov

Wrong Private/Public Key Pair: Ensure keys match

# Verify key pair matches
from phlow.utils import verify_keypair
is_valid = verify_keypair(private_key, public_key)

Malformed Agent ID: Agent ID in header doesn't match token claims

# Ensure agent_id matches between token and request header
headers = {"X-Agent-ID": "same-agent-id-as-in-token"}

"Agent not found in registry" Error

Symptoms:

AgentNotFoundError: Agent my-agent-id not found

Solutions:

Check Supabase Registration: Verify agent is in database

SELECT * FROM agents WHERE agent_id = 'your-agent-id';

Register Agent: If not found, register first

await middleware.register_agent(agent_card)

Check Agent ID Format: Ensure consistent naming

# Agent ID should be URL-safe and consistent
agent_id = "my-agent-2024"  # Good
agent_id = "my agent!"      # Bad - spaces and special chars

Supabase Connection Issues

"Could not connect to Supabase" Error

Symptoms:

ConnectionError: Could not connect to Supabase

Debugging Steps:

Verify Environment Variables:

echo $SUPABASE_URL
echo $SUPABASE_ANON_KEY

Test Connection:

from supabase import create_client
supabase = create_client(url, key)
response = supabase.table('agents').select('*').limit(1).execute()
print(response)

Check Network Access:

curl -H "apikey: YOUR_ANON_KEY" "YOUR_SUPABASE_URL/rest/v1/"

"RLS Policy Violation" Error

Symptoms:

PostgrestAPIError: new row violates row-level security policy

Solutions:

Apply Database Schema: Ensure RLS policies are set up

psql -h db.xxx.supabase.co -U postgres -d postgres -f docs/database-schema.sql

Check Service Role: For admin operations, use service role key

# Use service role for admin operations
supabase_admin = create_client(url, service_role_key)

Performance Issues

Slow Authentication

Symptoms: - Authentication takes >2 seconds - High CPU usage during JWT verification

Solutions:

Enable Key Caching: Use encrypted key store

from phlow.security import EncryptedFileKeyStore
key_store = EncryptedFileKeyStore("/secure/path")

Add Redis for Rate Limiting: Reduce database load

rate_config = RateLimitConfig(
    redis_url="redis://localhost:6379"
)

Monitor Circuit Breakers: Check if external calls are timing out

# Check circuit breaker status
from phlow.monitoring import get_circuit_breaker_status
status = get_circuit_breaker_status()

Memory Leaks

Symptoms: - Memory usage grows over time - Application becomes slow after extended use

Solutions:

Check HTTP Client Cleanup: Ensure proper resource cleanup

# Always close HTTP clients
async with httpx.AsyncClient() as client:
    # Use client here
    pass

Monitor Cache Size: DID document cache may grow large

# Configure cache size limits
from phlow.rbac import configure_did_cache
configure_did_cache(max_size=1000, ttl=3600)

Development Issues

Import Errors

Symptoms:

ImportError: cannot import name 'PhlowMiddleware'

Solutions:

Check Installation: Ensure Phlow is properly installed

pip list | grep phlow
uv pip install phlow[fastapi]  # With FastAPI support

Virtual Environment: Ensure you're in the correct environment
```
which python
pip show phlow
```

Testing Issues

Symptoms: - Tests fail with authentication errors - Supabase connections in tests

Solutions:

Use Test Configuration: Mock Supabase for unit tests

from unittest.mock import Mock

# Mock Supabase client
mock_supabase = Mock()
config.supabase_client = mock_supabase

Environment Variables: Set test environment

export SUPABASE_URL="http://localhost:54321"
export SUPABASE_ANON_KEY="test-key"

Production Issues

Rate Limiting Errors

Symptoms:

RateLimitExceededError: Rate limit exceeded for agent

Solutions:

Increase Rate Limits: Adjust configuration

rate_config = RateLimitConfig(
    requests_per_minute=120,  # Increase limit
    burst_size=30
)

Implement Backoff: Add retry logic with exponential backoff

import asyncio

async def retry_with_backoff(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await func()
        except RateLimitExceededError:
            if attempt < max_retries - 1:
                await asyncio.sleep(2 ** attempt)
            else:
                raise

Circuit Breaker Trips

Symptoms:

CircuitBreakerOpenError: Circuit breaker is open

Solutions:

Check External Dependencies: Verify Supabase/Redis health
```
curl -f $SUPABASE_URL/health
redis-cli ping
```

Adjust Circuit Breaker Settings: Tune thresholds

from phlow.monitoring import configure_circuit_breaker
configure_circuit_breaker(
    failure_threshold=10,
    timeout_seconds=60
)

Monitoring and Debugging

Enable Debug Logging

import logging
logging.basicConfig(level=logging.DEBUG)

# Or use structured logging
from phlow.monitoring import configure_logging
configure_logging(level="DEBUG", format="json")

Health Check Endpoints

@app.get("/health")
async def health_check():
    try:
        # Test Supabase connection
        supabase.table('agents').select('agent_id').limit(1).execute()
        return {"status": "healthy", "timestamp": datetime.utcnow()}
    except Exception as e:
        return {"status": "unhealthy", "error": str(e)}

Prometheus Metrics

from phlow.monitoring import enable_prometheus_metrics
enable_prometheus_metrics(port=9090)

# Monitor these metrics:
# - phlow_auth_requests_total
# - phlow_auth_duration_seconds
# - phlow_rate_limit_hits_total
# - phlow_circuit_breaker_state

Getting Help

Enable Verbose Logging

import os
os.environ["PHLOW_LOG_LEVEL"] = "DEBUG"
os.environ["PHLOW_ENABLE_AUDIT_LOGGING"] = "true"

Collect Diagnostic Information

from phlow.diagnostics import collect_diagnostics

# Generates diagnostic report
diagnostics = collect_diagnostics()
print(diagnostics)

Common Log Patterns

Successful Authentication:

{
  "level": "info",
  "message": "Agent authenticated successfully",
  "agent_id": "my-agent",
  "request_id": "req-123"
}

Failed Authentication:

{
  "level": "warning",
  "message": "JWT verification failed",
  "agent_id": "my-agent",
  "error": "Token expired",
  "request_id": "req-124"
}

Rate Limit Hit:

{
  "level": "warning",
  "message": "Rate limit exceeded",
  "agent_id": "my-agent",
  "current_rate": "65/min",
  "limit": "60/min"
}

Still having issues? Check the GitHub Issues or create a new issue with:

Phlow version (pip show phlow)
Python version (python --version)
Environment (development/production)
Complete error traceback
Minimal reproduction code