🐰 RabbitMQ Error: 'failed to import definitions' From definitions.json on Boot

Exact Error Message

[error] <0.291.0> Failed to import definitions: validation failed:
{error,{invalid_definitions_file,
  "Definition file schema validation failed"}}

[error] <0.291.0> Failed to import definitions: {error,eacces}
[warning] <0.291.0> Could not import definitions from file
  "/etc/rabbitmq/definitions.json": file does not exist or cannot be read

Depending on the failure you may instead see JSON decoding error, vhost '/analytics' does not exist, or user 'app' already exists when the loaded definitions conflict with or reference missing objects.

What It Means

RabbitMQ can load a declarative definitions.json at boot to recreate vhosts, users, permissions, queues, exchanges, bindings, policies, and parameters. This is driven by load_definitions (or the newer definitions.import_backend / definitions.local.path settings) in rabbitmq.conf. When the broker starts, it reads that file and applies every object.

The error means the import step failed. Either the file cannot be read (wrong path, permissions), it is not valid JSON, it fails schema validation, or the objects inside it reference things that don’t line up (a queue in a vhost that isn’t defined, a policy for a missing exchange). Depending on your configuration, a failed import can either log a warning and continue with an empty topology or abort the boot step entirely — both leave you without the topology you expected.

Common Causes

• The configured path is wrong or the rabbitmq user can’t read the file (eacces).
• The file is not valid JSON — a trailing comma, unquoted key, or truncated export.
• Schema/validation failure: a required field is missing, or the file was hand-edited into an invalid shape.
• Objects are declared out of dependency order or reference a vhost/user that the file itself does not create.
• The export came from a newer RabbitMQ version and contains fields the running node rejects.
• Secrets/hashes: password hashing_algorithm in the file doesn’t match the node’s configured algorithm.

Diagnostic Commands

Find the exact import error and the path RabbitMQ tried to read:

grep -iE 'import definitions|definitions.json|invalid_definitions' \
  /var/log/rabbitmq/rabbit@$(hostname -s).log | tail -n 20

Confirm which definitions setting is active:

grep -iE 'load_definitions|definitions' /etc/rabbitmq/rabbitmq.conf

Validate the JSON is well-formed before the broker ever reads it:

python3 -m json.tool /etc/rabbitmq/definitions.json > /dev/null && echo "JSON OK"

Check ownership and permissions on the file:

ls -l /etc/rabbitmq/definitions.json

Step-by-Step Resolution

1. Read the log line — it tells you whether the failure is I/O (eacces, file not found), JSON parsing, or schema validation. Fix the category it names.

2. If it is a permissions/path problem, correct ownership and confirm the path in config matches the file on disk:

chown rabbitmq:rabbitmq /etc/rabbitmq/definitions.json
chmod 640 /etc/rabbitmq/definitions.json

3. If it is invalid JSON, validate and repair it. json.tool prints the line and column of the first syntax error:

python3 -m json.tool /etc/rabbitmq/definitions.json

4. Regenerate the file from a known-good source rather than hand-editing. Export from a healthy node to get a schema-valid file:

rabbitmqadmin export /etc/rabbitmq/definitions.json
# or, without the CLI tool:
rabbitmqctl export_definitions /etc/rabbitmq/definitions.json

5. If validation fails on references, make sure every vhost and user used by a queue, policy, or permission is also defined in the same file. Import manually to see the first offending object:

rabbitmqctl import_definitions /etc/rabbitmq/definitions.json

6. Restart the broker and confirm the import is clean and the topology is present:

systemctl restart rabbitmq-server
rabbitmqctl list_vhosts
rabbitmqctl list_queues name messages --vhost /

Importing definitions in file /etc/rabbitmq/definitions.json ... done

Prevention

• Always generate definitions.json with export_definitions/rabbitmqadmin export, never by hand, so it stays schema-valid.
• Validate the file in CI with json.tool (or a JSON schema check) before it ships to a node.
• Keep the password hashing_algorithm in the file consistent with the node’s rabbitmq.conf setting.
• Ensure the file is owned by rabbitmq and readable only by it; a bad eacces fails the import silently in some configs.
• Version the definitions file alongside your infrastructure code and re-export it after topology changes.
• Test a fresh boot against a scratch node before rolling a new definitions file to production.

Related Errors

• BOOT FAILED — a broader startup failure where a config or schema step aborts the whole boot, not just the import.
• vhost '/x' does not exist — a runtime reference to a vhost the definitions never created.
• user '...' already exists — a conflict between imported users and users already on the node.
• JSON decoding error — the parsing-level variant of an invalid definitions file.

Frequently Asked Questions

Does a failed import stop RabbitMQ from starting? It depends on your configuration; some setups abort the boot step while others log a warning and continue with no topology, so always confirm your queues actually exist after boot.

How do I create a valid definitions.json? Export it from a running, healthy node with rabbitmqctl export_definitions or rabbitmqadmin export; do not build the JSON by hand.

Why does my hand-edited file fail schema validation? Definitions have a strict schema, so a missing required field, a wrong type, or an object referencing an undefined vhost/user will be rejected — regenerate from an export instead.

Can I test a definitions file without restarting? Yes, run rabbitmqctl import_definitions <file> against a scratch node to surface the first offending object. Describe your import error in the DevOps AI prompt library for a tailored fix, or see more RabbitMQ guides.