WebSocket Debugger

Analyzes and debugs Django Channels WebSocket issues in this project.

Project Context

• WebSocket framework: Django Channels
• ASGI server: Daphne (in Docker)
• Message broker: Redis (channel layer)
• Authentication: JWT tokens via middleware
• Main consumer: core/agents/consumers.py
• Routing: core/agents/routing.py
• Middleware: core/agents/middleware.py

WebSocket Architecture

Client (React)
    ↓ WebSocket connect
    ↓ ws://localhost:8000/ws/chat/<conversation_id>/
ASGI (Daphne)
    ↓ TokenAuthMiddleware (JWT auth)
ChatConsumer
    ↓ Redis channel group
    ↓ Celery task queue
LangGraph Agent
    ↓ Stream responses
    ↓ Redis pub/sub
ChatConsumer → Client

When to Use

• "WebSocket not connecting"
• "Connection rejected/closed"
• "Messages not being received"
• "Streaming not working"
• "Authentication failing on WebSocket"
• "Redis channel issues"
• "Code 4001/4003 errors"

Connection Close Codes

Debugging Approach

1. Check Connection

// Frontend: Check WebSocket readyState
// 0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED
console.log(ws.readyState);

2. Verify Authentication

• Check JWT token is valid and not expired
• Verify token is passed correctly in query params or headers
• Check TokenAuthMiddleware is processing token

3. Check CORS/Origin

• Verify CORS_ALLOWED_ORIGINS in Django settings
• Check browser console for CORS errors
• Origin must match exactly (including port)

4. Verify Redis Connection

# Check Redis is running
docker compose exec redis redis-cli ping

# Monitor Redis pub/sub
docker compose exec redis redis-cli monitor

5. Check Channel Layer

# Django shell - test channel layer
from channels.layers import get_channel_layer
channel_layer = get_channel_layer()
# Should not be None

Common Issues

WebSocket connection refused:

# Check Daphne is running
docker compose logs web | grep -i daphne

# Verify ASGI config
# config/asgi.py should have ProtocolTypeRouter

4001 Authentication error:

# Check middleware chain in config/asgi.py
application = ProtocolTypeRouter({
    "websocket": TokenAuthMiddleware(
        URLRouter(websocket_urlpatterns)
    ),
})

Messages not received:

# Check Celery worker is processing
docker compose logs celery

# Check Redis channel groups
docker compose exec redis redis-cli keys "asgi:*"

Connection drops after 60s:

• Implement heartbeat/ping-pong
• Check for proxy timeouts (nginx, load balancer)

Key Files to Check

core/agents/
├── consumers.py      # ChatConsumer - main WebSocket handler
├── routing.py        # WebSocket URL patterns
├── middleware.py     # JWT authentication middleware
├── tasks.py          # Celery tasks for message processing
└── ws_connection_tokens.py  # Connection token management

config/
├── asgi.py           # ASGI application config
└── settings.py       # CHANNEL_LAYERS, CORS settings

frontend/src/
├── services/websocket.ts  # WebSocket client
└── hooks/useChat.ts       # Chat hook with WS

Testing WebSocket

# Test script
python scripts/test_websocket.py

# Manual test with websocat
websocat "ws://localhost:8000/ws/chat/test-123/?token=YOUR_JWT"

# Or using wscat
wscat -c "ws://localhost:8000/ws/chat/test-123/" -H "Authorization: Bearer YOUR_JWT"

Docker Logs

# Web server (Daphne) logs
docker compose logs -f web

# Redis logs
docker compose logs -f redis

# Celery worker logs
docker compose logs -f celery