BullMQ Stalled Job Verdict

Decides whether a BullMQ worker can SILENTLY EXECUTE A JOB MORE THAN ONCE. Pure function over your configuration: no I/O, no Redis, no dependency on bullmq.

Built for bullmq 6.0.8 (MIT). Not affiliated with or endorsed by the BullMQ project.

THE MEASUREMENT, against a REAL Redis. Stalled detection lives in BullMQ's Lua scripts and depends on real key expiry, so an in-memory mock cannot reproduce it. Two workers, one job, attempts:1. Worker A blocks its event loop for 4s against a 1s lock -- which is not contrived, since any CPU-bound step does exactly that:

  PROCESSOR RAN ON      : worker-A, worker-B
  times the job RAN     : 2
  'completed' fired for : worker-B
  'failed' messages     : (none)
  worker 'error' events : Missing lock for job 1. moveToFinished

TWO EXECUTIONS. ONE COMPLETION. NO FAILURE. The side effects happened twice and the ledger records once -- and the only trace is on the worker's `error` channel, which most codebases never subscribe to because completed and failed look like the complete set.

attempts:1 DOES NOT MEAN "RUNS AT MOST ONCE". It bounds retries after a FAILURE, and a stall is not a failure, so re-delivery happens outside the attempts budget entirely. That is not a careless misreading -- the option is called attempts.

RAISING lockDuration DOES NOT FIX A BLOCKED EVENT LOOP. The lock-renewal timer runs ON the loop, so a processor that blocks it cannot renew at any value; a bigger number only widens the window before the same thing happens. A large JSON.parse, a synchronous crypto call, an image resize or a tight loop over a big array all do this. So the blocked-loop case is reported independently of every number, and the remedy says so instead of suggesting a setting.

IT REPORTS: duplicate execution; a blocked loop that no setting protects; that attempts does not bound executions; a non-idempotent side effect that charges twice, sends twice, inserts twice; and whether the duplicate would be invisible because nothing listens to the error channel. Worst first, so a caller who reads only the top finding reads that the job can run twice.

IT REFUSES rather than guesses on an unknown runtime -- the assumption that saves work is "our jobs are quick", and the measured case was a job doing four seconds of CPU work. But it does NOT refuse when the loop can already block, because the answer is settled and burying a definite finding under a question is its own failure. A quick, non-blocking job well inside its lock is SAFE.

THE REMEDY IS IDEMPOTENCY, NOT A BIGGER NUMBER: at-least-once is what a lock-based queue actually offers.

VERIFIED: 18 tests, measured by running the suite, every mutation observed FAILING before restore.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateStalledRisk(config: Config): Verdict;

  export type Verdict = | { status: "SAFE";