Troubleshooting & FAQ
Diagnose and fix common kubemq-celery issues — connection failures, tasks not executing, duplicate runs, missing results, and monitoring gaps.
This guide collects the issues you are most likely to hit running Celery on KubeMQ, grouped by symptom: connection failures, tasks that do not execute or run twice, missing results, the "unknown transport" import error, and monitoring gaps. Each entry gives the cause and a concrete fix. For the underlying transport model see Concepts; for every option referenced here see Transport Options.
Connection issues
Task issues
Configuration issues
Performance issues
Monitoring issues
KubeMQ vs Redis — issue comparison
| Issue | Redis behavior | KubeMQ behavior |
|---|---|---|
| Message loss on restart | Lost unless AOF/RDB persistence is configured | Persistent storage by default |
| Duplicate task execution | Visibility-timeout race causes duplicates | Native ack/nack (no duplicates with acks_early) |
| Worker connection drops | Silent failure, manual recovery | gRPC keepalive, auto-reconnect via Celery retry |
| DLQ for failed tasks | Manual implementation | Native max_receive_count + dead_letter_queue |
| Delayed-task OOM | Tasks held in worker memory (client polling) | Server-side delay_in_seconds (zero worker memory) |
| Connection exhaustion | 6–8 TCP connections per worker | 2–3 gRPC connections (HTTP/2 multiplexed) |
| Queue-depth monitoring | Custom scripts or Redis CLI | REST /queue/info on 9090 plus the Management API dashboard on 8080 |
| Broker failover | Sentinel or Cluster mode required | Kubernetes-native StatefulSet auto-clustering |
When Redis may still be appropriate
- Sub-millisecond latency for small payloads (Redis is in-memory).
- Existing Redis infrastructure already deployed and managed.
- Result retention beyond 24 hours — KubeMQ caps expiration at
86400seconds. - Native O(1) chord unlock — KubeMQ uses a polling fallback (see Canvas Workflows).
Related
Was this page helpful?
Scheduling & Delayed Delivery
Schedule Celery tasks with countdown, ETA, and Celery Beat on KubeMQ using native server-side delay_in_seconds.
Configuration Reference
Reference for kubemq-celery — broker URL schemes, public API, Celery settings, environment variables, monitoring commands, and exceptions.