bullmq

Postconditions — what we check

• add · queue-add-redis-error

  error
  WhenRedis connection fails or is down during add operation
  ThrowsError with Redis connection failure details
  Required handlingCaller MUST wrap Queue.add() in try-catch to handle Redis connection errors. Redis downtime crashes application if unhandled. Use try-catch to gracefully degrade or retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• addBulk · queue-addbulk-redis-error

  error
  WhenRedis connection fails during bulk operation
  ThrowsError causing partial or complete bulk operation failure
  Required handlingCaller MUST wrap Queue.addBulk() in try-catch to handle Redis errors. Bulk operations can partially fail if Redis connection is lost - must handle to prevent data loss.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• process · worker-process-job-error

  warning
  Whenjob processing throws error or promise rejects
  ThrowsError causing job to fail and trigger retry logic if configured
  Required handlingWorker processor SHOULD handle job errors gracefully with try-catch to control retry behavior and provide meaningful error messages. Unhandled errors in processor can cause worker to stop processing subsequent jobs.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• close · close-error

  warning
  Whenconnection close operation fails (timeout, Redis error)
  ThrowsError during connection cleanup
  Required handlingCaller SHOULD handle close() errors during graceful shutdown to ensure proper cleanup. Use try-catch in shutdown handlers to log but not crash on close errors.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• run · worker-run-no-error-listener

  error
  WhenWorker started without 'error' event listener attached
  ThrowsUnhandled Error event from EventEmitter when Redis errors occur
  Required handlingCaller MUST attach worker.on('error', handler) BEFORE calling worker.run(). Without an error listener, Node.js throws an unhandled error event that crashes the process. The BullMQ docs explicitly warn: 'If the error handler is missing, your worker may stop processing jobs when an error is emitted.'
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• run · worker-run-redis-connection-error

  error
  WhenRedis connection fails during worker main loop
  ThrowsError emitted via 'error' event on worker instance
  Required handlingCaller MUST wrap Worker usage with error event listeners. Redis connection loss during run() causes the worker to emit 'error' events. Without maxRetriesPerRequest set to null for consumers, the worker will throw after retry limit is reached.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• FlowProducer.add · flow-add-redis-error

  error
  WhenRedis connection fails during atomic flow addition
  ThrowsError with Redis connection failure details
  Required handlingCaller MUST wrap FlowProducer.add() in try-catch. Flow additions are atomic (all-or-nothing) via Redis transactions, but Redis connection failure during the transaction causes the entire flow to fail. Without error handling, background pipeline orchestration silently stops.
  costhighin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[5]
• FlowProducer.addBulk · flow-addbulk-redis-error

  error
  WhenRedis connection fails during bulk flow addition
  ThrowsError with Redis connection failure details
  Required handlingCaller MUST wrap FlowProducer.addBulk() in try-catch. Bulk flow additions are atomic — Redis failure loses all flows in the batch. Must handle to prevent silent pipeline breakage.
  costhighin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[5]
• upsertJobScheduler · scheduler-upsert-redis-error

  error
  WhenRedis connection fails during scheduler upsert
  ThrowsError with Redis connection failure details
  Required handlingCaller MUST wrap upsertJobScheduler() in try-catch. Scheduler creation failure means recurring jobs silently stop being produced. This is especially dangerous during deployment — if scheduler registration fails, no cron jobs run until the next successful registration.
  costhighin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[6]
• pause · queue-pause-redis-error

  warning
  WhenRedis connection fails during pause operation
  ThrowsError with Redis connection failure details
  Required handlingCaller SHOULD wrap pause() in try-catch. Pause failure during maintenance windows means jobs continue processing when they should be stopped. Handle errors to verify pause actually took effect.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[1]
• resume · queue-resume-redis-error

  warning
  WhenRedis connection fails during resume operation
  ThrowsError with Redis connection failure details
  Required handlingCaller SHOULD wrap resume() in try-catch. Resume failure means the queue stays paused — jobs accumulate in waiting state without being processed. Must verify resume succeeded.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[1]
• obliterate · queue-obliterate-active-jobs-error

  error
  WhenQueue has active jobs and force option is not set
  ThrowsError indicating queue cannot be obliterated with active jobs
  Required handlingCaller MUST wrap obliterate() in try-catch. The method throws if there are active jobs and force=false. Additionally, this is an iterative SCAN-based operation — large queues may fail mid-obliteration on Redis errors, leaving the queue in a partially destroyed state.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• waitUntilFinished · job-wait-until-finished-timeout

  error
  WhenJob does not complete within the specified TTL
  ThrowsError indicating job timed out
  Required handlingCaller MUST wrap waitUntilFinished() in try-catch. The promise rejects on both job failure AND timeout. Using waitUntilFinished() in request-response patterns (e.g., HTTP handler waits for job result) without timeout handling causes hung requests. Always set a TTL parameter.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• waitUntilFinished · job-wait-until-finished-job-failed

  error
  WhenThe job fails during processing
  ThrowsError with the job's failedReason
  Required handlingCaller MUST handle rejection from waitUntilFinished(). When the job's processor throws, this promise rejects with the failure reason. Without try-catch, the calling code gets an unhandled rejection.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• Job.remove · job-remove-locked-error

  error
  WhenJob is currently being processed by a worker (locked)
  ThrowsError indicating job is locked and cannot be removed
  Required handlingCaller MUST wrap job.remove() in try-catch. Active jobs have locks and cannot be removed — the method throws rather than silently failing. Handle this to implement retry-after-completion logic.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[7]
• Job.retry · job-retry-invalid-state

  error
  WhenJob is not in failed or completed state, or job does not exist
  ThrowsError indicating job cannot be retried (wrong state, locked, or missing)
  Required handlingCaller MUST wrap job.retry() in try-catch. The method throws if the job is locked, does not exist, or is not in a finished state. Handle errors to avoid crashing retry-management code.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[8]
• clean · queue-clean-redis-error

  warning
  WhenRedis connection fails during clean operation
  ThrowsError with Redis connection failure details
  Required handlingCaller SHOULD wrap clean() in try-catch. Clean operations run Lua scripts against Redis — connection failures leave the queue in an inconsistent state. Handle errors in maintenance/cron code to prevent silent cleanup failures.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[1]
• drain · queue-drain-redis-error

  warning
  WhenRedis connection fails during drain operation
  ThrowsError with Redis connection failure details
  Required handlingCaller SHOULD wrap drain() in try-catch. Drain failure during deployment/maintenance means stale jobs remain in queue. Handle to verify drain completed.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[1]
• retryJobs · queue-retryjobs-redis-error

  warning
  WhenRedis connection fails during batch retry operation
  ThrowsError with Redis connection failure details
  Required handlingCaller SHOULD wrap retryJobs() in try-catch. Batch retry operations iterate over potentially large job sets — Redis failure mid-iteration causes partial retries. Handle to track which jobs were actually retried.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[8]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]docs.bullmq.io/guide/queueshttps://docs.bullmq.io/guide/queues
2. [2]docs.bullmq.io/guide/workershttps://docs.bullmq.io/guide/workers
3. [3]docs.bullmq.io/guide/connectionshttps://docs.bullmq.io/guide/connections
4. [4]docs.bullmq.io/patterns/failing-fast-when-redis-is-downhttps://docs.bullmq.io/patterns/failing-fast-when-redis-is-down
5. [5]docs.bullmq.io/guide/flowshttps://docs.bullmq.io/guide/flows
6. [6]docs.bullmq.io/guide/job-schedulershttps://docs.bullmq.io/guide/job-schedulers
7. [7]docs.bullmq.io/guide/jobshttps://docs.bullmq.io/guide/jobs
8. [8]docs.bullmq.io/guide/retrying-failing-jobshttps://docs.bullmq.io/guide/retrying-failing-jobs