🚨 RabbitMQ Error Guide: 'No compatible authentication mechanism' — Fix SASL Mechanism Mismatch

Overview

During connection negotiation the client and broker could not agree on a SASL authentication mechanism, so the handshake failed before any login was attempted:

Error: no compatible authentication mechanism found -
server offered: [AMQPLAIN, EXTERNAL], client supports: [PLAIN]

AMQP negotiates auth via SASL: the server advertises the mechanisms it will accept and the client picks one it also implements. If the intersection is empty, the connection is closed here — this is a configuration mismatch, not a wrong password.

Symptoms

• Connections fail immediately at handshake with no compatible authentication mechanism or mechanism ... is not enabled.
• The error names the server-offered and client-supported mechanism lists.
• Auth worked until auth_mechanisms was changed or TLS client-cert (EXTERNAL) auth was introduced.
• Only some clients fail — those that don’t implement the mechanism the server now requires.
• The broker log shows AMQP connection ... rejected at the security handshake step.

Common Root Causes

• PLAIN disabled on the server — auth_mechanisms was restricted (e.g. to EXTERNAL only) but the client only offers PLAIN.
• EXTERNAL required without a client cert — the broker expects TLS client-certificate auth but the client presents no cert (or PLAIN).
• Mechanism not enabled — a mechanism the client wants (e.g. AMQPLAIN) isn’t in the broker’s auth_mechanisms list.
• OAuth/plugin backend mismatch — a token backend expects a specific mechanism the client isn’t using.
• Legacy client — an old library only implements one mechanism the hardened broker no longer offers.
• Typo in config — a malformed auth_mechanisms entry drops the intended mechanism.

Diagnostic Workflow

Check which mechanisms the broker is configured to offer:

rabbitmqctl environment | grep -iA3 auth_mechanisms
rabbitmqctl eval 'application:get_env(rabbit, auth_mechanisms).'

Confirm the enabled auth backends (relevant for EXTERNAL / OAuth):

rabbitmqctl eval 'application:get_env(rabbit, auth_backends).'

Read the handshake rejection in the log to see the negotiated lists:

grep -iE 'authentication mechanism|rejected|EXTERNAL|PLAIN' \
  /var/log/rabbitmq/rabbit@$(hostname -s).log | tail

If EXTERNAL is in play, verify TLS and client-cert config:

rabbitmq-diagnostics listeners
rabbitmqctl environment | grep -iE 'ssl|verify|fail_if_no_peer_cert'

Example Root Cause Analysis

After a security hardening change, a batch of services began failing at connect with no compatible authentication mechanism found - server offered: [EXTERNAL], client supports: [PLAIN].

rabbitmqctl eval 'application:get_env(rabbit, auth_mechanisms).' showed the broker had been set to offer only EXTERNAL (TLS client-certificate auth). The updated services presented certs; the failing legacy services still used username/password (PLAIN), which the broker no longer offered.

Because those legacy services could not be re-tooled immediately, the fix was to offer both mechanisms during the transition, keeping EXTERNAL as the preferred path:

auth_mechanisms.1 = EXTERNAL
auth_mechanisms.2 = PLAIN

After restarting nodes with the updated rabbitmq.conf, PLAIN clients reconnected while cert clients kept using EXTERNAL. Root cause: the broker’s advertised mechanism set no longer intersected with what the legacy clients supported.

Prevention Best Practices

• Change auth_mechanisms in a staged way — add the new mechanism alongside the old, migrate clients, then remove the old.
• Inventory which mechanism each client library uses before hardening the broker’s advertised set.
• For EXTERNAL/TLS-cert auth, verify every client actually presents a valid cert before making it the only mechanism.
• Keep auth_mechanisms identical across all cluster nodes so behavior doesn’t depend on which node a client hits.
• Alert on handshake rejections in the log; a spike right after a config change points straight at the mismatch.

Quick Command Reference

rabbitmqctl eval 'application:get_env(rabbit, auth_mechanisms).'   # offered mechanisms
rabbitmqctl eval 'application:get_env(rabbit, auth_backends).'     # backends (EXTERNAL/OAuth)
rabbitmq-diagnostics listeners                                    # TLS listeners for EXTERNAL
grep 'authentication mechanism' /var/log/rabbitmq/*.log

Conclusion

no compatible authentication mechanism is a negotiation failure: the broker’s advertised SASL mechanisms don’t intersect with what the client supports. Check auth_mechanisms on the server, confirm the client’s mechanism (PLAIN vs. EXTERNAL/cert vs. OAuth), and offer both during a transition rather than cutting over hard. Keep the mechanism set consistent across nodes and staged during hardening so no client is left without a common mechanism.