Skip to main content
The current adapter supports BullMQ 5.81.5+ within v5 and 6.3.11+ within v6. New queues can use v6. Existing legacy repeat records must be migrated with v5 first.

​
Review configuration

  • The default queue name is agentium-jobs. Colons are not accepted in queue names. Set the same valid name on every producer and worker.
  • Retry configuration belongs to producer defaultJobOptions or individual enqueue options. Removed worker attempts / backoffDelay fields never controlled BullMQ jobs.
  • Prefer schedule({ id, cron, timezone, agent | team | workflow }) with exactly one target. A stable ID updates the scheduler.
  • enqueue*({ repeat }) derives an ID from the payload/options; changing the payload changes that ID.

​
Migrate persisted schedules

Perform maintenance using BullMQ v5, with a Redis backup and original application payloads/options available.
  1. Stop schedule writers. Pause the queue, let active jobs finish, then stop workers. Legacy removal requires a paused queue with zero active jobs.
  2. Save listLegacySchedules(). This inventory contains keys, names, cron, timezone, and next timestamp; it is not a complete payload backup.
  3. Choose stable replacement IDs. Remove each legacy key with removeLegacySchedule(key) before calling schedule() to create its replacement.
  4. Verify the whole legacy inventory is empty and listSchedules() contains exactly the intended IDs. Close the v5 maintenance client.
  5. Deploy v6 workers and writers. Verify the scheduler inventory again, resume the queue, and enable writers.
Do not run old and new schedule writers concurrently. On v6, legacy maintenance methods fail; schedule operations refuse queues containing legacy metadata.

​
Roll back

Stop v6 workers/writers and return to v5 with the queue paused and drained. Remove replacement scheduler IDs with unschedule(), restore original repeat options and payloads or the Redis backup, verify the inventory, then restart the old deployment. Do not restore legacy records while replacements remain active. See scheduling for ordinary scheduler use and durable delivery when execution itself needs recovery.