🚨 RabbitMQ Error Guide: 'ACCESS_REFUSED - vhost not found' No Access to Virtual Host

Exact Error Message

This error stops a connection at the moment the client tries to open a virtual host. The user authenticated successfully, but the requested vhost either does not exist or the user has no permission to it. RabbitMQ refuses the connection.open and closes the connection.

2026-06-29 13:05:42.117 [error] <0.31288.4> Error on AMQP connection <0.31288.4> (10.0.6.42:48810 -> 10.0.4.21:5672, state: opening):
{handshake_error,opening,{amqp_error,not_allowed,"vhost 'orders' not found",none}}

When the vhost exists but the user lacks access to it:

2026-06-29 13:07:19.555 [error] <0.31402.4> Error on AMQP connection <0.31402.4> (10.0.6.42:48902 -> 10.0.4.21:5672, state: opening):
{handshake_error,opening,{amqp_error,access_refused,"access to vhost 'prod' refused for user 'orders-svc'",none}}

Clients report ACCESS_REFUSED - vhost 'orders' not found or ACCESS_REFUSED - access to vhost 'prod' refused for user 'orders-svc'.

What the Error Means

A virtual host (vhost) is RabbitMQ’s namespace for queues, exchanges, bindings, and permissions. Connecting requires selecting exactly one vhost via connection.open. Two distinct failures share this error class, both at state: opening:

• vhost '...' not found — the broker has no vhost by that name. The string the client sent does not match any existing vhost (often a missing vhost or an encoding mistake).
• access to vhost '...' refused — the vhost exists, but the authenticated user has no permission entry for it. Permissions are per-vhost; access to one grants nothing in another.

The default vhost is /, which must be URL-encoded as %2F in AMQP URIs. A surprising number of “vhost not found” errors are actually a mis-encoded /.

Common Causes

1. The vhost was never created

A new environment or a fresh node has only the default / vhost. An app configured for prod or orders fails until that vhost is added.

2. User has no permission in the target vhost

Permissions are scoped per vhost. A user created with permissions only in / is refused when opening prod, even with valid credentials.

3. Mis-encoded default vhost in the URI

amqp://user:pass@host:5672/ (trailing slash) selects the empty-named vhost, not /. The default must be amqp://user:pass@host:5672/%2F.

4. Wrong vhost name in client config

A typo, environment mix-up (staging vs stage), or stale config points the client at a vhost that does not exist on this broker.

5. Vhost deleted or not yet imported

The vhost was removed during cleanup, or a definitions.json import has not run on a rebuilt node, so the expected vhost is absent.

How to Reproduce the Error

Point a client at a vhost that does not exist, and separately at one the user cannot access:

# 1) Non-existent vhost -> "vhost 'nope' not found"
rabbitmqadmin -u guest -p guest -V nope list queues

# 2) Existing vhost the user lacks permission on -> "access to vhost ... refused"
rabbitmqctl add_vhost prod
rabbitmqctl add_user limited 'pw' 2>/dev/null
# note: no set_permissions on 'prod' for 'limited'
rabbitmqadmin -u limited -p pw -V prod list queues

The first call reports the vhost is not found; the second reports access refused because limited has no permission entry in prod.

Diagnostic Commands

# List all vhosts the broker knows about
rabbitmqctl list_vhosts name

# Show which users have permissions in a given vhost
rabbitmqctl list_permissions -p prod

# Show all vhosts a specific user can access
rabbitmqctl list_user_permissions orders-svc

# Confirm the default vhost exists and is healthy
rabbitmqctl list_vhosts name cluster_state

# Catch the exact opening failure (not found vs refused) in the log
sudo journalctl -u rabbitmq-server -f | grep -E "vhost .* not found|access to vhost"

Step-by-Step Resolution

Step 1: Decide which of the two failures you have

Read the log string. “vhost ’…’ not found” means the vhost is missing or mis-named/encoded. “access to vhost ’…’ refused” means it exists but the user has no permission.

Step 2: For “not found”, verify the vhost list and the client string

rabbitmqctl list_vhosts name

If the vhost is genuinely absent, create it. If it should exist, check the client URI — a trailing / selects the empty vhost; the default must be %2F.

rabbitmqctl add_vhost prod

Step 3: For “access refused”, grant per-vhost permissions

# configure  write  read  (adjust regexes to least privilege)
rabbitmqctl set_permissions -p prod orders-svc '.*' '.*' '.*'

Step 4: Fix the client connection string

Ensure the vhost segment is correct and URL-encoded. For default vhost use %2F; for a named vhost use its exact name (case-sensitive).

amqp://orders-svc:pass@10.0.4.21:5672/prod
amqp://guest:guest@10.0.4.21:5672/%2F     # default vhost

Step 5: Verify the connection opens

Reconnect and confirm with rabbitmqctl list_connections name vhost user state that the connection is running in the expected vhost.

Prevention and Best Practices

• Provision vhosts as part of environment setup (Terraform, definitions.json, or a bootstrap script) so a fresh node never lacks the vhosts apps expect.
• Always URL-encode the default vhost as %2F; a bare trailing slash is the most common false “vhost not found.”
• Grant per-vhost permissions explicitly when creating service users — authentication alone does not grant any vhost.
• Keep vhost names consistent across environments and validate them in client config at startup rather than failing at first connect.
• Back up and version definitions.json so vhosts, users, and permissions are restored together after a rebuild.
• For fast triage, the free incident assistant can tell “not found” from “access refused” and point to the fix.

Related Errors

• ACCESS_REFUSED - access to queue/exchange ... refused for user — authorization within a vhost the user can already access.
• ACCESS_REFUSED - Login was refused for user — authentication failure that occurs before any vhost is selected.
• PLAIN login refused: user ... does not exist — the user account itself is missing.
• Error on AMQP connection ... state: opening — the generic lifecycle line that wraps this vhost failure.

More in the RabbitMQ guides.

Frequently Asked Questions

Why do I get “vhost not found” when the vhost clearly exists? Almost always a client URI issue. A trailing / selects the empty-named vhost, and / must be encoded as %2F. Compare the exact string in the log against rabbitmqctl list_vhosts — names are case-sensitive.

What is the difference between “vhost not found” and “access to vhost refused”? “Not found” means no vhost by that name exists on the broker. “Access refused” means the vhost exists but the authenticated user has no permission entry in it. The first needs add_vhost or a corrected name; the second needs set_permissions.

Does creating a user grant access to any vhost? No. A new user has zero vhost permissions until you run set_permissions -p <vhost>. They can authenticate but cannot open any vhost, so they hit “access to vhost refused.”

How do I encode the default vhost in a connection URI? Use %2F. For example, amqp://guest:guest@host:5672/%2F. Leaving the path empty or as a bare / does not select the / vhost.

My vhost disappeared after a node rebuild — why? If the vhost was not in a restored definitions.json or recreated by bootstrap automation, a rebuilt node starts with only the default /. Always restore definitions so vhosts, users, and permissions come back together.