Redis Retry Strategy#

redisQueueRetryOptions is the central retry configuration object used by every BullMQ queue and worker in Langfuse. It is defined in packages/shared/src/server/redis/redis.ts and spread into every createNewRedisInstance() call across 30+ queue files under packages/shared/src/server/redis/.

The retryStrategy Function#

The retry function uses pure exponential backoff — no jitter:

delay = clamp(Math.exp(times), 1_000, 20_000) // milliseconds

Key properties 1:

• Retries forever — there is no return null branch that would permanently abandon the connection
• Minimum 1 s — Math.max(..., 1000) prevents instant storm-retry bursts at startup
• Maximum 20 s — Math.min(..., 20000) caps the ceiling
• No jitter — all queue connections will retry in lockstep after a Redis restart; this can be a source of synchronized reconnect thundering herd if many queue connections are lost simultaneously
• A logger.warn fires once times >= 5 to surface persistent connectivity issues 2

reconnectOnError Behavior#

The reconnectOnError handler:

• Returns false for MOVED errors — these are normal ioredis cluster redirects, not real connection failures
• Returns 2 for READONLY errors — ioredis return value 2 means "reconnect and automatically replay the failed command." This handles read replicas that become the master during a failover

Scope: What Uses These Options#

redisQueueRetryOptions is applied to 3:

• Every BullMQ Queue singleton — passed as additionalOptions to createNewRedisInstance({ enableOfflineQueue: false, ...redisQueueRetryOptions })
• Every BullMQ Worker connection — WorkerManager.register() calls createNewRedisInstance(redisQueueRetryOptions) to create each worker's dedicated Redis connection 4

It does not apply to the global redis singleton used for non-queue operations 5, which uses only defaultRedisOptions.

Base Connection Defaults (defaultRedisOptions)#

Applied to all connections regardless of queue vs. non-queue use 6:

• maxRetriesPerRequest: null — no per-request retry cap; required by BullMQ
• keepAlive: 10_000 ms — prevents middleboxes from killing idle connections
• socketTimeout: 30_000 ms — forces reconnect if no data is received; prevents hung moveToCompleted() from blocking concurrency slots
• enableAutoPipelining — controlled by REDIS_ENABLE_AUTO_PIPELINING env var (default "true")

Environment Variable Configuration#

The retry delay values (1000–20000 ms) and the exponential formula are hardcoded — there are no REDIS_RETRY_* environment variables 7. Environment variables cover connection details, TLS, cluster, and Sentinel topology but not retry timing:

Known Issue: Sentinel Mode Gap#

redisQueueRetryOptions sets retryStrategy (for data-node reconnects) and reconnectOnError, but does not set sentinelRetryStrategy — the separate ioredis callback for retrying the sentinel sweep when all sentinel addresses are temporarily unreachable 8.

During a Redis data-node failover, ioredis's default sentinel retry runs at 10 ms intervals. This causes a feedback loop: each failed sentinel sweep emits an error event, which triggers the outer retryStrategy timer, spawning additional concurrent connect() calls with fresh retryAttempts = 0. In severe cases this can exhaust file descriptors and leave all worker connections permanently broken 8.

Two mitigations have been merged:

• PR #15478 (guardSentinelDisconnect) — suppresses BullMQ's watchdog disconnect(reconnect=true) call when the ioredis client is in "connecting" status (the Sentinel master-resolution window), preventing it from entering a terminal "end" state 9
• PR #15512 — adds an opt-in ?failIfQueueConsumptionStuck=true health check endpoint that returns HTTP 503 if no BullMQ job activity is observed for LANGFUSE_QUEUE_CONSUMPTION_STUCK_THRESHOLD_MINUTES (default 60 min), enabling Kubernetes to auto-restart wedged workers 10

Adding an explicit sentinelRetryStrategy with a longer backoff (e.g., Math.min(retries * 200, 10_000)) to createRedisSentinelInstance remains an open community suggestion 8.