Retrying failing jobs

Search…
Retrying failing jobs
When a processor throws an exception, the worker will catch it and move the job to the failed set. But sometimes, it may be desirable to retry a failed job.
BullMQ supports retries of failed jobs using backoff functions. It is possible to use the built in backoff functions or provide custom ones.
For BullMQ to reschedule failed jobs, make sure you create a QueueScheduler for your queue.
The code below shows how to specify a "exponential" backoff function with a 1 second delay as seed value, so it will retry at most 3 times spaced after 1 second, 2 seconds and 4 seconds:
1
import { Queue, QueueScheduler } from 'bullmq';
2
​
3
const myQueue = new Queue('foo');
4
const myQueueScheduler = new QueueScheduler('foo');
5
​
6
await queue.add(
7
  'test-retry',
8
  { foo: 'bar' },
9
  {
10
    attempts: 3,
11
    backoff: {
12
      type: 'exponential',
13
      delay: 1000,
14
    },
15
  },
16
);
Copied!
You can also define it in the queue's defaultJobOptions, and it will apply to all jobs added to the queue, unless overridden. For example:
1
import { Queue, QueueScheduler } from 'bullmq';
2
​
3
const myQueue = new Queue('foo', {
4
  defaultJobOptions: {
5
    attempts: 3,
6
    backoff: {
7
      type: 'exponential',
8
      delay: 1000,
9
    },
10
  },
11
});
12
​
13
const myQueueScheduler = new QueueScheduler('foo');
14
​
15
await queue.add('test-retry', { foo: 'bar' });
Copied!
The current built-in backoff functions are "exponential" and "fixed".
With an exponential backoff, it will retry after 2 ^ attempts * delay milliseconds. For example, with a delay of 3000 milliseconds, for the 7th attempt, it will retry 2^7 * 3000 milliseconds = 6.4 minutes after the previous attempt. With a fixed backoff, it will retry after delay milliseconds, so with a delay of 3000 milliseconds, it will retry every attempt 3000 milliseconds after the previous attempt.
If you want to define your custom backoff you need to define it at the worker:
1
import { Worker } from 'bullmq';
2
​
3
const worker = new Worker('foo', async job => doSomeProcessing(), {
4
  settings: {
5
    backoffStrategies: {
6
      custom(attemptsMade: number) {
7
        return attemptsMade * 1000;
8
      },
9
    },
10
  },
11
});
Copied!
You can then use your "custom" strategy when adding jobs:
1
import { Queue } from 'bullmq';
2
​
3
const myQueue = new Queue('foo');
4
​
5
await queue.add(
6
  'test-retry',
7
  { foo: 'bar' },
8
  {
9
    attempts: 3,
10
    backoff: {
11
      type: 'custom',
12
    },
13
  },
14
);
Copied!
Stop retrying jobs
When a processor throws an exception that is considered as unrecoverable, you should use the UnrecoverableError class.
BullMQ supports moving jobs to failed when this error is thrown without retrying to process it.
1
import { Worker, UnrecoverableError } from 'bullmq';
2
​
3
const worker = new Worker('foo', async job => {doSomeProcessing();
4
throw new UnrecoverableError('Unrecoverable');
5
}, {
6
  connection
7
  },
8
});
9
​
10
await queue.add(
11
  'test-retry',
12
  { foo: 'bar' },
13
  {
14
    attempts: 3,
15
    backoff: 1000,
16
  },
17
);
Copied!
Guide - Previous
Rate limiting
Next - Guide
Returning job data
Last modified 2mo ago
Copy link
Contents
Retrying failing jobs
Stop retrying jobs