Troubleshooting

Common issues and solutions.

CDC Pipeline

Debezium Not Connecting

Symptoms: No CDC events, Debezium logs show connection errors.

Solutions:

1. Check PostgreSQL is running and healthy
2. Verify wal_level = logical
3. Check credentials in application.properties
4. Ensure replication slots are available

# Check WAL level
docker exec ds-postgres psql -U datastream -c "SHOW wal_level;"

# Check replication slots
docker exec ds-postgres psql -U datastream -c "SELECT * FROM pg_replication_slots;"

Events Not Arriving

Symptoms: Debezium healthy, but no events in NATS.

Solutions:

1. Check NATS JetStream is enabled
2. Verify stream exists
3. Check table include list

# Check NATS streams
curl -s http://localhost:8222/jsz | jq

# Check Debezium health
curl -s http://localhost:8080/q/health

Streaming

WebSocket Closes Immediately

Symptoms: onclose fires right after onopen.

Solutions:

1. Check game slug is valid
2. Verify Redis connection
3. Look at backend logs

# Check backend logs
docker logs ds-backend --tail 100

# Test with curl
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: test" -H "Sec-WebSocket-Version: 13" \
  http://localhost:3000/ws/crash

SSE No Events

Symptoms: Initial event received, but no updates.

Solutions:

1. Verify Redis Pub/Sub
2. Check consumer is running
3. Generate test data

# Test Redis Pub/Sub
redis-cli SUBSCRIBE stream:crash &
redis-cli PUBLISH stream:crash '{"test":true}'

# Generate test round
task db:simulate

High Latency

Symptoms: Events delayed by seconds.

Solutions:

1. Check network connectivity
2. Reduce batch sizes
3. Scale consumer

# Check NATS consumer lag
nats consumer info ROUNDS consumer-name

Redis

Connection Refused

Solutions:

1. Verify Redis is running
2. Check connection URL
3. Check firewall rules

# Test Redis connection
redis-cli -h localhost -p 6379 ping

Out of Memory

Solutions:

1. Configure maxmemory
2. Set TTL on keys
3. Use LRU eviction

# Check memory usage
redis-cli INFO memory

Backend

404 on Endpoints

Solutions:

1. Check route registration
2. Verify game slug
3. Look at Fiber logs

Rate Limited

Symptoms: HTTP 429 responses.

Solutions:

1. Reduce request rate
2. Implement client-side caching
3. Use streaming instead of polling

Docker

Container Won't Start

# Check logs
docker compose logs service-name

# Check health
docker compose ps

# Rebuild
docker compose up -d --build service-name

Network Issues

# List networks
docker network ls

# Inspect network
docker network inspect data-stream_default

Getting Help

1. Check logs: docker compose logs -f
2. Verify health: docker compose ps
3. Test endpoints: curl http://localhost:3000/api/games
4. Open issue on GitHub