🚨 RabbitMQ Error Guide: 'ACCESS_REFUSED' Login Was Refused (403)

Overview

An ACCESS_REFUSED error is RabbitMQ rejecting the AMQP login. Unlike a connection refused (which fails at TCP), this happens during the AMQP handshake: the TCP connection succeeded, but authentication or authorization failed. The broker returns a 403-style refusal and closes the connection. It covers two distinct failures — wrong/disallowed credentials, and a valid user lacking permission on the requested vhost or resource.

You will see it on login failure:

ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN.
For details see the broker logfile.

The broker logfile shows the real reason:

operation none caused a connection exception access_refused:
"Login was refused for user 'app'. Wrong password or unknown user."

Or, when the user is valid but lacks vhost access:

access_refused: "access to vhost 'orders' refused for user 'app'"

The client message is deliberately vague (to avoid leaking which usernames exist); the broker log is where the actual cause lives.

Symptoms

• Connection completes the TCP layer, then fails during handshake with ACCESS_REFUSED.
• Client message says “Login was refused” or “access to vhost … refused”.
• Failure is identical across hosts using the same credentials/vhost — it is not network-dependent.

sudo grep -i 'access_refused\|Login was refused' /var/log/rabbitmq/rabbit@$(hostname -s).log | tail -5

=ERROR REPORT==== Login was refused for user 'app'. Wrong password or unknown user.
=ERROR REPORT==== access to vhost 'orders' refused for user 'reporter'.

The log distinguishes an auth failure (wrong password/unknown user) from an authz failure (vhost refused).

Common Root Causes

1. Wrong password or unknown user

The credential the client sends does not match any user.

rabbitmqctl list_users

Listing users ...
user    tags
guest   [administrator]
app     []

If the client logs in as worker but only app and guest exist, the login is refused as “unknown user”. A stale or rotated password produces the same “Wrong password” refusal.

2. The user has no permissions on the requested vhost

The user authenticates but has no configure/write/read grant on the vhost it tries to use.

rabbitmqctl list_user_permissions app

Listing permissions for user "app" ...
vhost   configure   write   read
/       .*          .*      .*

The user can use / but the client connects to vhost orders — no row for orders means access to vhost 'orders' refused.

3. The vhost does not exist

The client requests a vhost that was never created (or was deleted).

rabbitmqctl list_vhosts

Listing vhosts ...
name
/
billing

A client connecting to /orders when only / and /billing exist is refused — there is no such vhost to grant access to.

4. guest user restricted to loopback

By default guest can only connect from localhost. Remote clients using guest are refused even with the correct password.

rabbitmqctl environment | grep -A2 'loopback_users'

{loopback_users,[<<"guest">>]},

guest in loopback_users means any non-localhost guest login is refused. Real apps should use a dedicated user, not guest.

5. The user exists but has restrictive resource permissions

The user has a vhost grant, but the configure/write/read regex does not cover the queue/exchange it tries to use.

rabbitmqctl list_user_permissions publisher

vhost   configure   write       read
/       ^$          ^orders\.   ^$

publisher can write to orders.* but cannot configure (declare) or read anything. Declaring a queue or consuming triggers an access refusal on that operation.

6. The user is missing required tags or the password hashing changed

A management login needs a tag (management/administrator); and on cluster upgrades a changed password_hashing algorithm can invalidate stored hashes.

rabbitmqctl list_users
rabbitmqctl authenticate_user app 's3cr3t'

guest   [administrator]
app     []
Error: failed to authenticate user "app"

authenticate_user returning an error confirms the credential itself is rejected (wrong password or invalidated hash), independent of any client.

Diagnostic Workflow

Step 1: Read the broker log to classify auth vs. authz

sudo grep -iE 'Login was refused|access to vhost|access_refused' \
  /var/log/rabbitmq/rabbit@$(hostname -s).log | tail -10

“Wrong password or unknown user” = authentication. “access to vhost … refused” = authorization. They have different fixes.

Step 2: For an auth failure, verify the user and password

rabbitmqctl list_users
rabbitmqctl authenticate_user <USER> '<PASSWORD>'

If authenticate_user fails, the credential is wrong regardless of the client. Reset it if needed:

rabbitmqctl change_password <USER> '<NEW_PASSWORD>'

Step 3: For an authz failure, confirm the vhost exists

rabbitmqctl list_vhosts

If the requested vhost is missing, create it (or fix the client’s vhost):

rabbitmqctl add_vhost <VHOST>

Step 4: Inspect and set the user’s permissions on that vhost

rabbitmqctl list_user_permissions <USER>

Grant the needed configure/write/read on the vhost:

rabbitmqctl set_permissions -p <VHOST> <USER> '.*' '.*' '.*'

Tighten the regexes for production rather than .* once the app works.

Step 5: Handle the guest/loopback case

If the client uses guest remotely, switch it to a dedicated user. Only as a last resort lift the loopback restriction. Then retry the login.

rabbitmqctl add_user app 's3cr3t'
rabbitmqctl set_permissions -p / app '.*' '.*' '.*'

Example Root Cause Analysis

A reporting service that worked in staging fails in production with ACCESS_REFUSED - Login was refused. The same image and credentials run in both environments, so the team suspects a password problem.

Checking the broker log on the production node:

sudo grep -i 'access' /var/log/rabbitmq/rabbit@mq-01.log | tail -3

=ERROR REPORT==== access to vhost 'reporting' refused for user 'reporter'.

This is an authorization failure, not authentication — the password is fine, but the reporter user has no permission on the reporting vhost in production. Confirming:

rabbitmqctl list_user_permissions reporter

vhost   configure   write   read
/       .*          .*      .*

The provisioning script that grants reporting permissions had only run in staging; production created the reporter user but never ran the grant for the reporting vhost. Fix:

rabbitmqctl set_permissions -p reporting reporter '^$' '^$' '.*'

The reporter only needs read access, so configure/write are left empty. The service connects and consumes immediately. The vague client error hid an authz gap that the broker log named exactly.

Prevention Best Practices

• Never use guest for application clients — create a dedicated user per service so loopback restrictions and shared-credential rotations don’t cause refusals.
• Provision users, vhosts, and permissions together from one definitions file (rabbitmqctl import_definitions) so an environment can’t have a user without its grants.
• Grant least-privilege configure/write/read regexes per vhost and document them, so a missing grant is visible in review rather than discovered at runtime.
• Always check the broker logfile, not just the client error, when triaging ACCESS_REFUSED — the client message is intentionally vague.
• Validate credentials non-destructively with rabbitmqctl authenticate_user during deploys to catch rotated/invalidated passwords before traffic hits.
• For a quick auth-vs-authz read on an ACCESS_REFUSED page, the free incident assistant can classify the broker log line and point at the missing grant. More in the RabbitMQ guides.

Quick Command Reference

# Classify the failure from the broker log
sudo grep -iE 'Login was refused|access to vhost|access_refused' \
  /var/log/rabbitmq/rabbit@$(hostname -s).log | tail -10

# Users and credential check
rabbitmqctl list_users
rabbitmqctl authenticate_user <USER> '<PASSWORD>'

# Vhosts and per-user permissions
rabbitmqctl list_vhosts
rabbitmqctl list_user_permissions <USER>

# Grant access on a vhost
rabbitmqctl set_permissions -p <VHOST> <USER> '.*' '.*' '.*'

# Loopback-restricted users
rabbitmqctl environment | grep -A2 'loopback_users'

Conclusion

ACCESS_REFUSED is a handshake-time rejection — TCP succeeded but login did not. The usual root causes:

1. Wrong password or an unknown user.
2. A valid user with no permissions on the requested vhost.
3. A vhost that does not exist.
4. The guest user used remotely while restricted to loopback.
5. Resource regexes too narrow for the configure/write/read the client needs.

Read the broker logfile first to split authentication (“wrong password/unknown user”) from authorization (“access to vhost refused”), then fix the credential or the permission accordingly.