Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Feature: limit how many times a stalled job is recovered

Open
  • Is something wrong?
#53 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
node.js, typescript
Domain
backend, distributed-systems

Research direction

Start with Reaper's #recoverStalledJob and the requeue() path, then inspect job state handling and the enqueueAndWait failure path; DESIGN.md documents the at-least-once behavior. Run the provided stalled-handler reproduction, and consider the work done when a maxStalledCount limit produces the requested stored error, TTL, failed event, and JobFailedError behavior.

Written by the indexing model from the issue text.

Description

Running a job again after a stall is expected: the queue is at-least-once, and DESIGN.md says jobs "may be processed multiple times after crashes, lease expirations". But nothing limits how many times the same job is recovered. A job that reliably hangs or crashes its worker (a "poison" job) is recovered and re-run indefinitely, tying up a worker each time and never reaching a terminal state. maxAttempts doesn't help, because it only counts handler failures, and a stalled job never produces one.

Example

@platformatic/[email protected] (also on main). The handler ignores cancellation and never settles, so every run stalls:

import { MemoryStorage, Queue, Reaper } from '@platformatic/job-queue'
import { setTimeout as sleep } from 'node:timers/promises'

const visibilityTimeout = 500
const storage = new MemoryStorage()
const queue = new Queue({ storage, visibilityTimeout, concurrency: 10 })
const reaper = new Reaper({ storage, visibilityTimeout })

// The handler ignores cancellation and never settles, so every run stalls.
let runs = 0
queue.execute(job => {
  console.log(`run #${++runs}: job.attempts = ${job.attempts}`)
  return new Promise(() => {})
})

await queue.start()
await reaper.start()
await queue.enqueue('stuck', {}, { maxAttempts: 1 })

await sleep(visibilityTimeout * 4 + 200)
console.log(`maxAttempts was 1, the job ran ${runs} times`)

await reaper.stop()
await queue.stop()
await storage.disconnect()

run #1: job.attempts = 1
run #2: job.attempts = 1
run #3: job.attempts = 1
run #4: job.attempts = 1
run #5: job.attempts = 1
maxAttempts was 1, the job ran 5 times

(The count here is capped by the 10 consumer slots the stuck handlers occupy. A job that crashes its worker process would instead be recovered after every restart.)

Proposal

Add a limit on stall recoveries, e.g. a maxStalledCount option, as BullMQ has. When a job exceeds it, fail it the same way as a final handler failure: store an error, apply the error TTL, emit failed, and reject enqueueAndWait callers with JobFailedError.

Implementation notes

  • The count has to be stored with the job and updated together with the requeue. Putting it in the message is awkward, because requeue() finds the processing entry by the original message bytes. So the job state is probably the better place.
  • #recoverStalledJob already writes failing:<ts>:<attempts + 1> into the state, but nothing reads the incremented value. That could become the stall counter, or the + 1 could be dropped.
  • Recovery requeues the job first and writes its state afterwards. Doing both atomically would keep it from overwriting a state written in between.

I'm happy to send a PR for this.

Dominant language
TypeScript
Stars
370
Forks
11
No merged PRs in 30d

Getting set up

  • Ships a Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from platformatic/job-queue

All issues in platformatic/job-queue

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.