> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Queue and schedule migration

> Move persisted BullMQ repeat records to stable Job Scheduler IDs before upgrading to v6.

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](/schedules/overview) for ordinary scheduler use and [durable delivery](/queue/durable) when execution itself needs recovery.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.