🚨 RabbitMQ Error Guide: 'plugins_not_found' — Fix Plugin Enable Failures

Overview

rabbitmq-plugins enable failed because the broker could not find a plugin with the name you gave it in any of its plugin directories:

Error:
{:plugins_not_found, [:rabbitmq_delayed_message_exchange]}

The command aborts without changing the enabled set. RabbitMQ only knows about plugins that exist as .ez archives (or expanded dirs) in its plugins path; a name that doesn’t resolve to a discoverable plugin produces this error.

Symptoms

• rabbitmq-plugins enable <name> exits non-zero with plugins_not_found and the offending name(s).
• rabbitmq-plugins list does not show the plugin at all (not even as disabled).
• A third-party plugin was copied onto the host but the broker won’t enable it.
• The plugin worked before an upgrade and now can’t be found.
• Enabling a bundled plugin fails on a stripped-down or containerized image.

Common Root Causes

• Misspelled or wrong plugin name — e.g. rabbitmq_delayed_message instead of rabbitmq_delayed_message_exchange, or omitting the rabbitmq_ prefix.
• Third-party plugin not installed — the .ez file was never placed in the plugins directory (community plugins like the delayed-message exchange are not bundled).
• Version mismatch — the plugin .ez was built for a different RabbitMQ/Erlang version and is ignored by the broker’s discovery.
• Wrong plugins directory — the .ez sits in a path the broker doesn’t scan; RABBITMQ_PLUGINS_DIR points elsewhere.
• Permissions — the plugins directory or .ez isn’t readable by the rabbitmq user.
• Upgrade dropped it — a package upgrade replaced the plugins dir and the custom .ez wasn’t carried over.

Diagnostic Workflow

List what the broker can actually see — if the plugin isn’t here, it’s a discovery problem, not an enable problem:

rabbitmq-plugins list
rabbitmq-plugins list -v | grep -i delayed

Find the directories the broker scans for plugins:

rabbitmq-plugins directories -s
rabbitmqctl environment | grep -i plugins

Check the plugin archive is present, readable, and version-appropriate:

ls -l /usr/lib/rabbitmq/plugins/ /var/lib/rabbitmq/plugins/ 2>/dev/null
ls -l $(rabbitmq-plugins directories -s | awk '{print $2}')

Confirm the broker and Erlang versions the plugin must match:

rabbitmqctl status | grep -iE 'rabbitmq version|erlang'

Example Root Cause Analysis

An operator tried to enable the community delayed-message exchange:

rabbitmq-plugins enable rabbitmq_delayed_message_exchange

It failed with {:plugins_not_found, [:rabbitmq_delayed_message_exchange]}. rabbitmq-plugins list | grep delayed returned nothing — the plugin was never installed. rabbitmq-plugins directories -s showed the plugins dir as /var/lib/rabbitmq/plugins, which was empty of third-party archives.

The fix was to download the .ez built for the exact broker version, drop it into the plugins directory with correct ownership, and re-enable:

sudo cp rabbitmq_delayed_message_exchange-*.ez /var/lib/rabbitmq/plugins/
sudo chown rabbitmq:rabbitmq /var/lib/rabbitmq/plugins/rabbitmq_delayed_message_exchange-*.ez
rabbitmq-plugins enable rabbitmq_delayed_message_exchange

rabbitmq-plugins list now showed it enabled. Root cause: a community plugin that must be installed manually and matched to the broker version was simply absent.

Prevention Best Practices

• Pin third-party plugin .ez versions to the broker version and bake them into your image or config-management, not by hand.
• After an upgrade, re-verify enabled plugins; package upgrades can reset the plugins directory.
• Reference the exact plugin name from rabbitmq-plugins list -v rather than memory.
• Keep custom plugins in a stable path and set RABBITMQ_PLUGINS_DIR explicitly so discovery is deterministic.
• Ensure the plugins directory and archives are owned by and readable by the rabbitmq user.

Quick Command Reference

rabbitmq-plugins list                    # what the broker can discover
rabbitmq-plugins directories -s          # dirs scanned for .ez plugins
rabbitmq-plugins enable <plugin_name>    # enable (validate the exact name)
rabbitmqctl status | grep -i version     # match plugin build to this version
ls -l /var/lib/rabbitmq/plugins/         # confirm the .ez is present + readable

Conclusion

plugins_not_found means the broker never discovered a plugin by that name — it’s a discovery problem, not a runtime failure. Confirm the exact name with rabbitmq-plugins list, check the archive is present and readable in a scanned directory (rabbitmq-plugins directories -s), and make sure the .ez matches the broker/Erlang version. For community plugins, install the correctly-versioned archive first, then enable. Bake plugin versions into your image so upgrades never lose them.