definitions export errors due to a missing metadata field

[DelineaSamGeorge]

Describe the bug

In both Windows and Linux (x64), definitions export returns valid data without arguments but returns "HTTP API request failed: error decoding response body" with underlying error "missing field metadata at line 1 column 25122" when any -t arg is used.

Reproduction steps

1. Download/Install 2.8.1
2. Run rabbitmqadmin --host [MYBUSINESS] --port 443 --username [ME] --password "[SWORDFISH]" --use-tls definitions export
3. Observe a valid response
4. Run rabbitmqadmin --host [MYBUSINESS] --port 443 --username [ME] --password "[SWORDFISH]" --use-tls definitions export -t no_op

Expected behavior

The exact same output.

Additional context

Version used is 2.8.1; this behavior also appears in 2.7.2
I'm connecting to CloudAMQP
I want to use -t prepare_for_quorum_queue_migration,drop_empty_policies so that I don't need to handle the transition more manually, but that doesn't work, either.

[michaelklishin]

I'm afraid I cannot reproduce, and several other members of my team have used --transformations heavily just recently.

rabbitmqadmin help | head -n 1
# => RabbitMQ CLI that uses the HTTP API. Version: 2.8.1

rabbitmqadmin definitions export --transformations no_op | jq

rabbitmqadmin definitions export --transformations exclude_users | jq

rabbitmqadmin definitions export --transformations prepare_for_quorum_queue_migration,drop_empty_policies | jq

all produce the output I expect against a 4.1.3 node.

[michaelklishin]

@DelineaSamGeorge I'm not going to do CloudAMQP support team's job for free, they directly make money off of RabbitMQ without contributing even 1% of the R&D.

But if you have a definitions file that can be used to reproduce this behavior against a local node, with TLS or without, 4.1.x or 3.13.x, I will be happy to use that to investigate what may be going on.

Storing GET /api/definitions output, removing the users part and renaming the virtual host should be a good starting point.

[michaelklishin]

@DelineaSamGeorge the metadata field is expected to be present on virtual hosts. This has been the case since rabbitmq/rabbitmq-server#2080, rabbitmq/rabbitmq-server#2012, that is, 3.8.0. Let's assume that it shipped in 3.9.0 in its current form.

So you can be running a 3.7.x or 3.8.x version of RabbitMQ, while Migrating from Classic Mirrored Queues to Quorum Queues in 2025 was tested against 3.13.x.

If my hypothesis is correct, what breaks response deserialization is the missing field in the response. It can be made optional easily. However, even 3.12.x series are entirely out of date by now, and you are not a paying user (or rather, you are paying to a company that does not care one bit about contributing to RabbitMQ).

I cannot know what else might be incompatible in those series that have long reached EOL, so I won't promise that rabbitmqadmin definitions export will support your versions even with the metadata field made optional.

[michaelklishin]

3.8.0 (a Version from 2019) Compatibility

Indeed, the metadata field comes from rabbitmq/rabbitmq-server@dbe1b02, which first shipped in 3.8.0 on Oct 1, 2019.

To verify:

docker run -d --name rabbitmq-3.8.0 -p 15672:15672 -p 5672:5672 rabbitmq:3.8.0-management

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/definitions | jq

that outputs

{
  "rabbit_version": "3.8.0",
  "users": [
    {
      "name": "guest",
      "password_hash": "w+HcIC9/nLMF7al8SUEaabe4AzwbXcIrMjqHUY11tlQ9xi6+",
      "hashing_algorithm": "rabbit_password_hashing_sha256",
      "tags": "administrator"
    }
  ],
  "vhosts": [
    {
      "name": "/"
    }
  ],
  "permissions": [
    {
      "user": "guest",
      "vhost": "/",
      "configure": ".*",
      "write": ".*",
      "read": ".*"
    }
  ],
  "topic_permissions": [],
  "parameters": [],
  "global_parameters": [
    {
      "name": "cluster_name",
      "value": "rabbit@789c89284c6d"
    }
  ],
  "policies": [],
  "queues": [],
  "exchanges": [],
  "bindings": []
}

The metadata field is not the only thing that rabbitmqadmin v2 expects: the tags field on a user is a string, not an array.

3.9.0 (a Version from 2021) Compatibility

Something is broken about the 3.9.0 community Docker image's aarch64 variant, so I'll skip it because 3.9.x has reached EOL in Jan 2023.

3.10.0 (a Version from 2022) Compatibility

docker run -d --name rabbitmq-3.10.0 -p 15672:15672 -p 5672:5672 rabbitmq:3.10.0-management

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/definitions | jq

produces

{
  "rabbit_version": "3.10.0",
  "rabbitmq_version": "3.10.0",
  "product_name": "RabbitMQ",
  "product_version": "3.10.0",
  "users": [
    {
      "name": "guest",
      "password_hash": "XWmvYdrI9xuVzsXDM2GdR0lRZfelejtUDuFSEZJRP32/AFk+",
      "hashing_algorithm": "rabbit_password_hashing_sha256",
      "tags": [
        "administrator"
      ],
      "limits": {}
    }
  ],
  "vhosts": [
    {
      "name": "/"
    }
  ],
  "permissions": [
    {
      "user": "guest",
      "vhost": "/",
      "configure": ".*",
      "write": ".*",
      "read": ".*"
    }
  ],
  "topic_permissions": [],
  "parameters": [],
  "global_parameters": [
    {
      "name": "internal_cluster_id",
      "value": "rabbitmq-cluster-id-yuqUd3rGR650uO2X6nkpPQ"
    }
  ],
  "policies": [],
  "queues": [],
  "exchanges": [],
  "bindings": []
}

So the metadata field is there but it's not populated, and would still run into the same exception as 3.8.0 did. But hey, at least the list of user tags is now an array, as rabbitmqadmin v2 expects it to be.

Using a locally built version where virtual host metadata is made optional, I get

cargo run '--' definitions export --transformations prepare_for_quorum_queue_migration,drop_empty_policies | jq

{
  "server_version": "3.10.0",
  "users": [
    {
      "name": "guest",
      "tags": [
        "administrator"
      ],
      "password_hash": "XWmvYdrI9xuVzsXDM2GdR0lRZfelejtUDuFSEZJRP32/AFk+"
    }
  ],
  "virtual_hosts": [
    {
      "name": "/",
      "tags": null,
      "description": null,
      "default_queue_type": null,
      "metadata": null
    }
  ],
  "permissions": [
    {
      "user": "guest",
      "vhost": "/",
      "configure": ".*",
      "read": ".*",
      "write": ".*"
    }
  ],
  "parameters": [],
  "policies": [],
  "queues": [],
  "exchanges": [],
  "bindings": []
}

So with a one line change michaelklishin/rabbitmq-http-api-rs#66, rabbitmqadmin definitions export can support RabbitMQ 3.10.x.

It's not like anyone on the core team cares about 3.10.x at this point but a one line change
that can allow more vintage versions upgrade to 4.x is acceptable.

Responsible Adults Do Not Run EOL Series of Infrastructure Software

Make no mistake: if you are still on RabbitMQ older than 3.13.x, it's your and your problem only.

[michaelklishin]

2.8.2 is out and rabbitmqadmin definitions export now can deserialize GET /api/definitions responses from nodes as old as 3.10.0.

Note that the README already states that the supported versions are 3.13.0 or later series. Don't expect any more pre-3.13.0 compatibility changes.

[DelineaSamGeorge]

That answers the question, thanks

[michaelklishin]

@DelineaSamGeorge may I clarify what RabbitMQ version are you migrating from?