Skip to main content

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