Unexpected management API response for cluster overview

Error message

Unexpected management API response for cluster overview

What it means

getOverview calls the RabbitMQ management API GET /api/overview and expects a JSON object. If the response is not a JSON object (unexpected shape), the library throws this error instead of returning malformed data. Usually indicates the endpoint returned an error page, proxy HTML, or an API version/path mismatch.

Source

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

		"version":     serverString(connection.Properties, "version"),
		"platform":    serverString(connection.Properties, "platform"),
		"nodes":       nodes,
		"nodeCount":   len(nodes),
	}, nil
}

func (s *server) getOverview(params jsonObject) (any, error) {
	connection, err := s.requireConnectionConfig(params)
	if err != nil {
		return nil, err
	}
	overview, err := managementGet(connection, "/api/overview")
	if err != nil {
		return nil, err
	}
	object, ok := overview.(map[string]any)
	if !ok {
		return nil, errors.New("Unexpected management API response for cluster overview")
	}
	return overviewInfoFromJSON(jsonObject(object)), nil
}

func overviewInfoFromJSON(overview jsonObject) jsonObject {
	info := jsonObject{}
	putIfPresent(info, "messagesReady", nestedLongOrNull(overview, "queue_totals", "messages_ready"))
	putIfPresent(info, "messagesUnacked", nestedLongOrNull(overview, "queue_totals", "messages_unacknowledged"))
	if stats := objectOrNil(overview, "message_stats"); stats != nil {
		putIfPresent(info, "publishRate", rateFromDetails(stats, "publish_details"))
		putIfPresent(info, "deliverRate", rateFromDetails(stats, "deliver_get_details"))
		putIfPresent(info, "ackRate", rateFromDetails(stats, "ack_details"))
	}
	putIfPresent(info, "totalQueues", nestedLongOrNull(overview, "object_totals", "queues"))
	putIfPresent(info, "totalExchanges", nestedLongOrNull(overview, "object_totals", "exchanges"))
	putIfPresent(info, "totalConnections", nestedLongOrNull(overview, "object_totals", "connections"))
	putIfPresent(info, "totalChannels", nestedLongOrNull(overview, "object_totals", "channels"))
	putIfPresent(info, "totalConsumers", nestedLongOrNull(overview, "object_totals", "consumers"))

View on GitHub (pinned to c0390bff16)

Solutions

Verify the management URL points to http(s)://host:15672/api and returns JSON (curl it)
Check for proxy/firewall injecting HTML error pages and exclude the management path
Confirm RabbitMQ management plugin version matches the driver's expectations
Check credentials: some auth failures return HTML rather than JSON

Example fix

// before
connection: { url: "http://localhost:5672" }   // AMQP port, not management API
// after
connection: { url: "http://localhost:15672" }  // management API port

Defensive patterns

Strategy: type-guard

Validate before calling

const res = await fetch(managementUrl + "/api/overview", { headers: authHeader });
const ct = res.headers.get("content-type") || "";
if (!ct.includes("application/json")) throw new Error("management API not returning JSON");

Type guard

function isOverview(v) { return v != null && typeof v === "object" && !Array.isArray(v); }

Try / catch

try { await agent.dispatch("getOverview", {}); } catch (e) { if (/Unexpected management API response/.test(e.message)) { /* check proxy/URL/credentials before retry */ } else throw e; }

Prevention

Point connections at the management port (15672), not the AMQP port
Exclude the management path from HTML-error-page proxies
Test with curl that /api/overview returns JSON
Keep RabbitMQ and driver versions aligned

When it happens

Trigger: Management API reachable but /api/overview returned a non-object: HTML error page, string body, JSON array, or empty response.

Common situations: Reverse proxy / load balancer intercepting the request; wrong management API port (15672 vs 5672) serving something else; auth error page returned with 200; very old RabbitMQ versions with different response shape.

Related errors

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