RabbitMQ Management API URL is required when AMQP uses non-d

Error message

RabbitMQ Management API URL is required when AMQP uses non-default port %d because the Management listener port is configured independently

What it means

RabbitMQ's Management API listens on its own port (default 15672/15671) configured independently of the AMQP listener. When no explicit management_url is given, the driver can only infer the management port if AMQP uses a default port (5672/5671). If AMQP runs on a custom port and management is not configured, inference is impossible and this error is thrown.

Source

Thrown at agents/drivers/rabbitmq/management.go:189

		}
	}
}

func managementBaseURLs(connection jsonObject) ([]string, error) {
	if explicit := stringOrNull(connection, "management_url"); explicit != nil && strings.TrimSpace(*explicit) != "" {
		return []string{normalizeManagementURL(*explicit)}, nil
	}
	tlsEnabled := managementTLS(connection)
	addresses, err := resolveAddresses(connection)
	if err != nil {
		return nil, err
	}
	port, configured := configuredManagementPort(connection, tlsEnabled)
	if !configured {
		for _, endpoint := range addresses {
			isDefaultAMQPPort := endpoint.Port == defaultAMQPPort || (tlsEnabled && endpoint.Port == defaultAMQPTLSPort)
			if !isDefaultAMQPPort {
				return nil, fmt.Errorf(
					"RabbitMQ Management API URL is required when AMQP uses non-default port %d because the Management listener port is configured independently",
					endpoint.Port,
				)
			}
		}
	}
	baseURLs := make([]string, 0, len(addresses))
	for _, endpoint := range addresses {
		baseURLs = append(baseURLs, managementBaseURL(endpoint.Host, port, tlsEnabled))
	}
	return baseURLs, nil
}

func managementBaseURL(host string, port int, tlsEnabled bool) string {
	scheme := "http"
	if tlsEnabled {
		scheme = "https"
	}

View on GitHub (pinned to c0390bff16)

Solutions

Set management_url in the connection config to the broker's management endpoint (e.g. http://host:15672)
Or configure the management port explicitly so configuredManagementPort reports it as configured
Or use the default AMQP port (5672, TLS 5671) so the driver can infer the management port
Verify the management plugin is listening on the URL you provide (rabbitmqctl status / curl)

Example fix

// before
connection = {"host": "broker", "port": 5673, "username": "app", "password": "pw"}
// after
connection = {"host": "broker", "port": 5673, "username": "app", "password": "pw", "management_url": "http://broker:15672"}

Defensive patterns

Strategy: validation

Validate before calling

func validateRabbitMQConfig(conn map[string]any) error {
    port, _ := conn["port"].(float64)
    mgmt, hasMgmt := conn["management_url"].(string)
    if port != 5672 && port != 5671 && (!hasMgmt || strings.TrimSpace(mgmt) == "") {
        return fmt.Errorf("custom AMQP port %v requires management_url", port)
    }
    return nil
}

Prevention

Always set management_url explicitly when using non-default AMQP ports
Add config validation at application startup
Document the management port next to the AMQP port in deployment configs
Health-check both AMQP and management endpoints in readiness probes

When it happens

Trigger: Configuring an AMQP endpoint with a non-default port (e.g. 5673) while omitting management_url (or the management port setting) in the connection object, then issuing any operation that needs managementRequest.

Common situations: Docker deployments remapping 5672 to a host port, brokers installed with a custom amqp listener in rabbitmq.conf, Kubernetes NodePort/LoadBalancer services exposing a non-standard AMQP port.

Related errors

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