Unexpected management API response for vhost listing

Error message

Unexpected management API response for vhost listing

What it means

listNamespaces calls the RabbitMQ management API endpoint /api/vhosts and expects the JSON response to decode into a JSON array. This error is thrown when the decoded response is not an []any (e.g. the management API returned an object such as {"error":"..."}, an error payload, or an unexpected shape) instead of a vhost array. It indicates the management API responded successfully at the HTTP layer but with data the driver cannot interpret as a vhost listing.

Source

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

			entry["prefetch"] = *prefetch
		}
		consumers = append(consumers, entry)
	}
	return consumers
}

func (s *server) listNamespaces(params jsonObject) (any, error) {
	connection, err := s.requireConnectionConfig(params)
	if err != nil {
		return nil, err
	}
	vhosts, err := managementGet(connection, "/api/vhosts")
	if err != nil {
		return nil, err
	}
	array, ok := vhosts.([]any)
	if !ok {
		return nil, errors.New("Unexpected management API response for vhost listing")
	}
	namespaces := make([]jsonObject, 0, len(array))
	for _, value := range array {
		vhost, ok := value.(map[string]any)
		if ok {
			namespaces = append(namespaces, jsonObject{"name": stringOrEmpty(jsonObject(vhost), "name")})
		}
	}
	return jsonObject{"namespaces": namespaces}, nil
}

func (s *server) createNamespace(params jsonObject) (any, error) {
	namespace, err := namespaceName(params)
	if err != nil {
		return nil, err
	}
	connection, err := s.requireConnectionConfig(params)
	if err != nil {

View on GitHub (pinned to c0390bff16)

Solutions

Verify the connection points at the RabbitMQ management HTTP port (default 15672), not the AMQP port, and that the management plugin is enabled (rabbitmq-plugins enable rabbitmq_management).
Check management credentials: log in with the same user via curl -u user:pass http://host:15672/api/vhosts and confirm a JSON array is returned.
Inspect any proxy/load balancer in front of the management API that may rewrite or block /api/vhosts.
Log the raw managementGet response body when this occurs to see what the server actually returned, then update the driver's decoding if the API shape changed.

Example fix

// before
array, ok := vhosts.([]any)
if !ok {
    return nil, errors.New("Unexpected management API response for vhost listing")
}
// after
array, ok := vhosts.([]any)
if !ok {
    return nil, fmt.Errorf("Unexpected management API response for vhost listing: got %T: %v", vhosts, vhosts)
}

Defensive patterns

Strategy: type-guard

Validate before calling

// Pre-check management API reachability/shape before calling listNamespaces
resp, err := http.Get("http://host:15672/api/vhosts") // with auth in practice
if err != nil || resp.StatusCode != 200 {
    return fmt.Errorf("management API not healthy: status %v", resp.StatusCode)
}

Type guard

func isVhostArray(v any) bool {
    arr, ok := v.([]any)
    if !ok { return false }
    for _, item := range arr {
        if _, ok := item.(map[string]any); !ok { return false }
    }
    return true
}

Try / catch

namespaces, err := agent.Call("listNamespaces", params)
if err != nil {
    if strings.Contains(err.Error(), "Unexpected management API response") {
        // log raw response, check management port/plugin/credentials, retry after fix
        return fmt.Errorf("management API returned non-array payload; verify port 15672 and rabbitmq_management plugin: %w", err)
    }
    return err
}

Prevention

Point the agent at the management HTTP port (15672) and enable rabbitmq_management.
curl /api/vhosts with your credentials and confirm a JSON array is returned before wiring the agent.
Check for proxies/load balancers that can replace the response body on errors.
Keep RabbitMQ and the driver in versions whose management API response shapes match.

When it happens

Trigger: managementGet(connection, "/api/vhosts") returns a decoded value that fails the type assertion vhosts.([]any) — typically because the management endpoint returned a JSON object (auth error body, HTML/plain-text error page, proxy response, or a non-standard management plugin response) instead of an array of vhosts.

Common situations: Wrong management API port or reverse proxy returning an error page; management credentials valid for HTTP but the endpoint path changed across RabbitMQ versions; a load balancer or management UI returning JSON error objects; pointing the agent at the AMQP port instead of the management HTTP port.

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

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