🚨 RabbitMQ Error Guide: 'access to vhost refused for user' — Fix vhost Permissions

Overview

The user authenticated successfully, but the broker refused to let them use the virtual host they connected to. The connection is dropped during the connection.open step, after the login succeeded:

ACCESS_REFUSED - access to vhost '/orders' refused for user 'app_svc'

Authentication (who you are) passed; authorization (what you can touch) failed. The credentials are valid, but that user has no permission entry on the requested vhost — a distinct failure from a bad password, which raises ACCESS_REFUSED - Login was refused.

Symptoms

• Clients connect, authenticate, then immediately disconnect with access to vhost 'X' refused.
• The broker log shows the refusal on connection.open with the exact vhost and user named.
• A service works against one vhost (often /) but fails against another it was repointed to.
• New deployments in a fresh vhost fail while the same credentials work elsewhere.
• rabbitmqctl list_permissions -p <vhost> does not list the user.

Common Root Causes

• No permission grant — the user exists but was never given permissions on this vhost with set_permissions.
• Wrong vhost in the connection string — a typo or a default / where the app needs /orders; vhost names are case-sensitive and URL-encoded in URIs (%2Forders).
• vhost recreated — the vhost was deleted and re-added, dropping all its permission entries.
• New user, forgotten grant — a user was created for a service but only tagged, never granted vhost permissions.
• Definitions import gap — a definitions export/import brought users and vhosts but the permissions block was incomplete.
• Deleted permissions — someone ran clear_permissions during cleanup.

Diagnostic Workflow

Confirm the vhost exists and is spelled exactly as the client uses it:

rabbitmqctl list_vhosts

Check whether the user has any permissions on that vhost:

rabbitmqctl list_permissions -p /orders
rabbitmqctl list_user_permissions app_svc

Confirm the user exists and its tags:

rabbitmqctl list_users

Read the broker log for the exact user/vhost pair being refused:

rabbitmqctl environment | grep log
# then, e.g.
grep 'access to vhost' /var/log/rabbitmq/rabbit@$(hostname -s).log

If a URI is in play, verify the encoded vhost — the path segment after the host is the vhost, and / must be encoded as %2F:

amqp://app_svc:secret@broker:5672/%2Forders

Example Root Cause Analysis

A service was migrated from the default vhost to a dedicated /orders vhost. Authentication kept working, but every connection dropped with access to vhost '/orders' refused for user 'app_svc'.

rabbitmqctl list_vhosts showed /orders existed. rabbitmqctl list_user_permissions app_svc returned only a row for / — the migration created the vhost and repointed the connection string but never granted app_svc permissions on the new vhost. Granting them fixed it immediately:

rabbitmqctl set_permissions -p /orders app_svc "^app_.*" "^app_.*" "^app_.*"

The three regexes are configure / write / read scopes. The connection succeeded on the next retry, confirming the root cause was a missing authorization grant, not authentication.

Prevention Best Practices

• Provision permissions in the same automation that creates a user or vhost — never create one without the other.
• Manage vhosts, users, and permissions declaratively (definitions file under GitOps) so a re-import always restores the full permissions block.
• Use least-privilege regexes scoped to the resource-name prefixes a service actually uses, rather than .*.
• Alert on access to vhost refusals in the log; a spike usually means a bad deploy or a dropped permission.
• Document the exact vhost (and its URI encoding) each service connects to, so repointing doesn’t silently lose access.

Quick Command Reference

rabbitmqctl list_vhosts                                  # confirm the vhost exists
rabbitmqctl list_user_permissions app_svc                # what can this user reach
rabbitmqctl list_permissions -p /orders                  # who can reach this vhost
rabbitmqctl set_permissions -p /orders app_svc "^app_.*" "^app_.*" "^app_.*"
rabbitmqctl clear_permissions -p /orders app_svc         # remove (for cleanup)

Conclusion

access to vhost refused for user is an authorization failure, not a login failure: the credentials are valid but the user has no permission entry on the requested virtual host. Verify the vhost name (and its URI encoding), confirm the user’s permissions with list_user_permissions, and grant scoped configure/write/read with set_permissions. Provision permissions alongside users and vhosts declaratively so the grant is never forgotten.