# Bullmq

> BullMQ — Redis-based distributed job and message queue for Node.js with workers, schedulers, flows, and rate limiting. Use when building with BullMQ or asking about its queues, workers, job configuration, repeatable jobs, flow producers, or Redis connection setup. Fetch live documentation for up-to-date details.

- Skill: `mikkelkrogsholm/bullmq` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mikkelkrogsholm/bullmq`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mikkelkrogsholm/bullmq/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: mikkelkrogsholm (https://skillmd.com/u/mikkelkrogsholm)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mikkelkrogsholm/bullmq

---


# BullMQ

> **CRITICAL: Your training data for BullMQ is unreliable.** APIs change between versions and memorized patterns may be wrong or deprecated. Before writing any code, you MUST use `WebFetch` to read the live docs:
>
> **`WebFetch("https://docs.bullmq.io/llms.txt")`**
>
> Do not proceed without fetching this URL first. Never assume an API exists — verify against current docs.

BullMQ is a Redis-based distributed job and message queue for Node.js with workers, schedulers, flows, and built-in rate limiting.
## Key Capabilities

BullMQ has built-ins that replace common patterns developers reach for external solutions to solve:

- **Flow Producers**: model parent-child job dependencies natively — no custom orchestration layer needed. A parent job only runs after all its children complete.
- **Sandboxed Processors**: run worker processors in isolated child processes (`processor: './worker.js'`) — no separate process manager or worker-threads wiring needed.
- **Job Schedulers**: built-in repeating job scheduler with cron and interval strategies. Note: `QueueScheduler` (v1) was removed in v2 when stall detection moved into `Worker`; the legacy `repeat` option on `queue.add()` was separately deprecated in v5.16+ in favor of `upsertJobScheduler()`. No `node-cron` needed.
- **Global Rate Limiting**: enforce a max-jobs-per-duration limit via the `limiter` option on the `Worker` constructor (`{ limiter: { max: 10, duration: 1000 } }`) — no Redis Lua scripting needed.
- **Built-in Metrics**: track processed/failed counts and Prometheus-compatible metrics without a separate metrics library.

## Best Practices

- **Always close connections explicitly**: `Queue`, `Worker`, and `QueueEvents` each hold their own Redis connection. Call `.close()` on all three on shutdown or you will leak connections and block process exit.
- **Use `QueueEvents` for cross-process event listening**: the `Worker` emits events only within its own process. To listen to completed/failed events from a different process (e.g. an API server), instantiate a `QueueEvents` object — not a `Worker`.
- **Job Schedulers replace Repeatable Jobs in v5.16+**: the old `repeat` option on `queue.add()` is deprecated. Use `queue.upsertJobScheduler()` instead to avoid duplicate scheduler entries on restart.
- **Set `removeOnComplete` and `removeOnFail`**: by default completed and failed jobs accumulate in Redis indefinitely. Always configure auto-removal (e.g. `{ count: 1000 }`) to prevent unbounded memory growth.
- **Do not share a single `IORedis` connection across multiple BullMQ instances**: BullMQ uses blocking Redis commands that require dedicated connections. Pass a connection config object (not a shared `IORedis` instance) so each class can create its own connection.