RabbitMQ rollback limits after an upgrade: what can definitions export actually restore?

The Ceiling of Definitions-Based Rollback

A definitions export is a snapshot of the broker's configuration (topology), not its state (data). If you rebuild a fresh cluster on the old version and import a definitions file, you restore the structural blueprint—vhosts, users, exchanges, queues, and bindings—but you start with empty queues. There is no supported way to use a definitions export to preserve or migrate message payloads or the replicated state of quorum queues.

Likely Explanation vs. Confirmed Facts

The confirmed behavior is that definitions capture only metadata: exchange, queue, and binding declarations, users, permissions, and vhost configuration. What is less certain—and worth testing in your environment—is how far back a given definitions file can be imported without schema conflicts, since that varies by version pair.

Addressing Your Specific Questions

• Is definitions export the ceiling? Yes, for a same-cluster rollback. Because a migrated data directory cannot be downgraded and many feature flags are one-way, the documented recovery path is a fresh old-version cluster plus definitions import. Preserving in-flight messages requires a different strategy: drain queues before upgrading, or use shovel/federation to move messages to a standby cluster during the cutover window. Neither is a rollback mechanism—they are pre-upgrade mitigation.
• Feature flags and schema changes: Definitions exports are generally importable across nearby versions, but they cannot undo an enabled feature flag. If the old version lacks a feature the definitions reference (for example, a queue type introduced later), the import of those specific entities may fail or be rejected. Test the exact version pair rather than assuming compatibility.
• Stopping the node before snapshotting: A clean shutdown before a filesystem snapshot guarantees consistency (no partially written files), which matters for backups of the current version. It does not change the downgrade picture: once a newer version migrates the internal schema, the old binary will typically refuse to start against that data directory regardless of how cleanly it was captured.

Verification Steps

1. Export definitions before upgrading via the Management UI or rabbitmqadmin export.
2. Spin up a clean instance of the old version in staging.
3. Import the JSON and confirm the topology is recreated.
4. Watch the server logs for 400 Bad Request or validation errors indicating incompatible definitions.
5. Rehearse the message-drain or shovel step so rollback-time data loss is bounded and measured, not discovered.

One detail that would change this recommendation: are you using stream queues or version-specific plugins? Those have their own storage and compatibility rules that can narrow the rollback window further.