t8y2/dbx · error

virtual_host is required

Error message

virtual_host is required

What it means

permissionVhost validates the virtual_host parameter for RabbitMQ permission operations (grantPermission, revokePermission, setPolicy, deletePolicy). RabbitMQ permissions and policies are scoped to a specific virtual host, so a non-empty virtual_host must be supplied. This library throws it when the parameter is missing or only whitespace.

Source

Thrown at agents/drivers/rabbitmq/operations.go:968

	if _, err := managementSend(connection, http.MethodDelete,
		"/api/permissions/"+urlEncodeVhost(vhost)+"/"+urlEncodePathSegment(user), nil); err != nil {
		return nil, err
	}
	return okResult(), nil
}

func permissionPattern(params jsonObject, key string) string {
	pattern := stringOrEmpty(params, key)
	if strings.TrimSpace(pattern) == "" {
		return defaultPermissionPattern
	}
	return pattern
}

func permissionVhost(params jsonObject) (string, error) {
	vhost := stringOrEmpty(params, "virtual_host")
	if strings.TrimSpace(vhost) == "" {
		return "", errors.New("virtual_host is required")
	}
	if vhost == "*" {
		return "", errors.New("all_vhosts is only supported for list operations")
	}
	return vhost, nil
}

func userName(params jsonObject) (string, error) {
	name := stringOrEmpty(params, "name")
	if strings.TrimSpace(name) == "" {
		name = stringOrEmpty(params, "user")
	}
	if strings.TrimSpace(name) == "" {
		return "", errors.New("user name is required")
	}
	return name, nil
}

View on GitHub (pinned to c0390bff16)

Solutions

1. Add a non-empty virtual_host parameter to the operation call
2. Verify the vhost name against `rabbitmqctl list_vhosts` or the listVirtualHosts operation
3. Do not use "*" for mutation operations; iterate over vhosts explicitly instead

Example fix

// before
{ "op": "grantPermission", "name": "alice", "pattern": ".*" }
// after
{ "op": "grantPermission", "name": "alice", "pattern": ".*", "virtual_host": "myapp-prod" }

const vhost = params.virtual_host?.trim();
if (!vhost) throw new Error("virtual_host is required");
if (vhost === "*") throw new Error("use a concrete vhost for mutating operations");

function hasVhost(p) { return typeof p.virtual_host === "string" && p.virtual_host.trim().length > 0; }

try { await agent.dispatch("grantPermission", params); } catch (e) { if (/virtual_host is required/.test(e.message)) { /* prompt for vhost and retry */ } else throw e; }

When it happens

Trigger: Calling grantPermission, revokePermission, setPolicy, or deletePolicy without a virtual_host param, or with virtual_host set to "" or whitespace only.

Common situations: Scripts built for list operations that omit virtual_host; config objects where virtual_host defaults to empty; copying calls from listCommands (which accept "*") into mutating commands.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• user name is required
• topic (queue name) is required
• namespace is required
• name is required
• password is required

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/c84356ad2cfa4330. Report an issue: GitHub.