What causes "multiple metrics server found" in cloudflare/cloudflared?

Stop extra cloudflared instances so exactly one metrics server is running, then retry.

ErrMultipleMetricsServerFound

ErrMultipleMetricsServerFound

Error message

multiple metrics server found

What it means

ErrMultipleMetricsServerFound is returned by FindMetricsServer when more than one cloudflared metrics server responds on the known addresses, making it ambiguous which instance a diagnostic should target. RunDiagnostic surfaces it, and the CLI subcommand handles it by listing all discovered instances (subcommands.go:1132).

Source

Thrown at diagnostic/error.go:25

var (
	// Error used when there is no log directory available.
	ErrManagedLogNotFound = errors.New("managed log directory not found")
	// Error used when it is not possible to collect logs using the log configuration.
	ErrLogConfigurationIsInvalid = errors.New("provided log configuration is invalid")
	// Error used when parsing the fields of the output of collector.
	ErrInsufficientLines = errors.New("insufficient lines")
	// Error used when parsing the lines of the output of collector.
	ErrInsuficientFields = errors.New("insufficient fields")
	// Error used when given key is not found while parsing KV.
	ErrKeyNotFound = errors.New("key not found")
	// Error used when there is no disk volume information available.
	ErrNoVolumeFound = errors.New("no disk volume information found")
	// Error user when the base url of the diagnostic client is not provided.
	ErrNoBaseURL = errors.New("no base url")
	// Error used when no metrics server is found listening to the known addresses list (check [metrics.GetMetricsKnownAddresses]).
	ErrMetricsServerNotFound = errors.New("metrics server not found")
	// Error used when multiple metrics server are found listening to the known addresses list (check [metrics.GetMetricsKnownAddresses]).
	ErrMultipleMetricsServerFound = errors.New("multiple metrics server found")
	// Error used when a temporary file creation fails within the diagnostic procedure
	ErrCreatingTemporaryFile = errors.New("temporary file creation failed")
)

View on GitHub (pinned to 2253eeeb25)

Solutions

Stop extra cloudflared instances so exactly one metrics server is running, then retry.
List the reported instances (the CLI logs them) and target the intended one explicitly via its metrics address.
Assign distinct --metrics addresses/ports per instance and query the specific one you need.
Handle errors.Is(err, diagnostic.ErrMultipleMetricsServerFound) by surfacing the instance list instead of failing.

Example fix

if errors.Is(err, diagnostic.ErrMultipleMetricsServerFound) {
	for _, s := range instances {
		log.Info().Msgf("instance: %s", s)
	}
	return nil
}

Defensive patterns

Strategy: try-catch

Try / catch

states, instances, err := diagnostic.FindMetricsServer(ctx, log)
if errors.Is(err, diagnostic.ErrMultipleMetricsServerFound) {
	log.Info().Msgf("Found multiple instances running:")
	// enumerate instances and pick or ask
}

Prevention

Run at most one cloudflared instance per host, or give each a distinct --metrics address.
Clean up orphaned cloudflared processes before running diagnostics.
Target a specific instance's metrics address instead of auto-discovery when multiple instances are expected.

When it happens

Trigger: Running a diagnostic command while two or more cloudflared processes are running with metrics servers on known addresses; FindMetricsServer returns the instances plus ErrMultipleMetricsServerFound at diagnostic/diagnostic_utils.go:140.

Common situations: Multiple concurrent tunnel runs (dev + service instance), leftover orphaned cloudflared processes, or running several replicas on one host each listening on a known metrics port.

Related errors

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/1578c21cad495040. Report an issue: GitHub.