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

code

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

javascript

// 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

bash

# 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

python

# 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:

bash

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

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

4001 Authentication error:

python

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

Messages not received:

bash

# 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

code

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

bash

# 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

bash

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

# Redis logs
docker compose logs -f redis

# Celery worker logs
docker compose logs -f celery