t8y2/dbx · error

Unexpected management API response for permission listing

Error message

Unexpected management API response for permission listing

What it means

listPermissions calls GET /api/permissions via managementGet and expects the JSON response to decode into a []any array. If the response is not an array (e.g. an error object, null, or an unexpected shape), the type assertion fails and the library raises this error instead of returning malformed data. It signals a mismatch between expected and actual management API response shape.

Source

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

func assertNotConnectedUser(action, name, connectedUser string) error {
	if name == connectedUser {
		return fmt.Errorf("Cannot %s user '%s' while connected as that user", action, name)
	}
	return nil
}

func (s *server) listPermissions(params jsonObject) (any, error) {
	connection, err := s.requireConnectionConfig(params)
	if err != nil {
		return nil, err
	}
	permissions, err := managementGet(connection, "/api/permissions")
	if err != nil {
		return nil, err
	}
	array, ok := permissions.([]any)
	if !ok {
		return nil, errors.New("Unexpected management API response for permission listing")
	}
	vhostFilter := stringOrEmpty(params, "virtual_host")
	if allVhostsRequested(params) {
		vhostFilter = ""
	}
	userFilter := stringOrEmpty(params, "user")
	result := make([]jsonObject, 0, len(array))
	for _, value := range array {
		permission, ok := value.(map[string]any)
		if !ok {
			continue
		}
		info := permissionInfoFromJSON(jsonObject(permission))
		if vhostFilter != "" && vhostFilter != stringOrEmpty(info, "vhost") {
			continue
		}
		if userFilter != "" && userFilter != stringOrEmpty(info, "user") {
			continue

View on GitHub (pinned to c0390bff16)

Solutions

1. Inspect the management API response directly (curl with management credentials to /api/permissions) to see what is actually returned.
2. Verify management API credentials and permissions — an auth error object instead of the array is the most common cause.
3. Confirm the management plugin is enabled and you are hitting the correct management API port (default 15672), not the AMQP port or a proxy.
4. Upgrade/align the driver with your RabbitMQ server version if the endpoint response shape changed.

Example fix

// before
resp, err := http.Get(baseURL + "/api/permissions") // hits proxy error page, body is HTML/object
permissions, err := managementGet(connection, "/api/permissions")
// after: verify endpoint and auth first
curl -u user:pass http://localhost:15672/api/permissions
// and only then, via the driver:
permissions, err := managementGet(connection, "/api/permissions")

func isPermissionList(resp any) bool {
    _, ok := resp.([]any)
    return ok
}
// usage:
// if !isPermissionList(permissions) { /* handle unexpected shape, log raw resp */ }

permissions, err := listPermissions(params)
if err != nil {
    if err.Error() == "Unexpected management API response for permission listing" {
        log.Printf("management API returned unexpected shape; check credentials/proxy, raw: %v", permissions)
        return fallbackPermissionCheck()
    }
    return err
}

When it happens

Trigger: The RabbitMQ management API returns a non-array body for GET /api/permissions — for example an error JSON object (401/403/404 payloads), a proxy/gateway error page, or a management plugin version/endpoint change that returns a different structure.

Common situations: Wrong vhost or insufficient permissions causing the management API to return an error object rather than the list; connecting through a reverse proxy or load balancer that intercepts the request (auth walls, HTML error pages); RabbitMQ management plugin version differences; targeting a non-management port or endpoint that answers with a different payload.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• Unexpected management API response for queue details
• Unexpected management API response for cluster overview
• Unexpected management API response for node listing
• No management API endpoint candidates
• Unexpected management API response for vhost listing

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