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

Code Meaning

4001 Authentication failed - user not authenticated

4003 CORS/Origin not allowed

4004 Rate limited

4005 Invalid message format

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