cloudflare/cloudflared · warning

ErrMetricsServerNotFound

ErrMetricsServerNotFound

Error message

metrics server not found

What it means

ErrMetricsServerNotFound is returned by FindMetricsServer when the known metrics addresses list yields zero running cloudflared instances, and propagates through RunDiagnostic. In cmd/cloudflared/tunnel/subcommands.go it is specifically matched with errors.Is and downgraded to a warning ('No instances found'), because it usually just means no tunnel instance is running locally.

Source

Thrown at diagnostic/error.go:23

)

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

1. Start a cloudflared tunnel instance and confirm its metrics server is listening before running diagnostics.
2. Check the tunnel's log to confirm the actual metrics address; pass a matching address if a custom --metrics port is used.
3. Handle errors.Is(err, diagnostic.ErrMetricsServerNotFound) gracefully as the CLI does — warn and exit 0.
4. Verify the process is running under the same user/namespace so its metrics port is reachable.

Example fix

states, err := diagnostic.RunDiagnostic(log, options)
if errors.Is(err, diagnostic.ErrMetricsServerNotFound) {
	log.Warn().Msg("No instances found")
	return nil
}

states, err := diagnostic.RunDiagnostic(log, options)
if errors.Is(err, diagnostic.ErrMetricsServerNotFound) {
	log.Warn().Msg("No instances found")
	return nil
}

When it happens

Trigger: Running diagnostic commands (cloudflared tunnel info/diag subcommands) when no cloudflared process is listening on any of the known metrics addresses (see metrics.GetMetricsKnownAddresses); FindMetricsServer finds len(instances) == 0 at diagnostic/diagnostic_utils.go:133.

Common situations: Invoking diagnostics before starting any tunnel, the tunnel having exited or crashed, metrics listener disabled/misconfigured (non-default metrics address), or querying from a different user/namespace than the running process.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• ErrMultipleMetricsServerFound
• --metrics has to be provided
• ErrNoVolumeFound
• ErrNoBaseURL
• ErrCreatingTemporaryFile

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