{"record":{"id":"e81fe886f93e7b8a","repo":"cloudflare/cloudflared","slug":"errmetricsservernotfound","errorCode":"ErrMetricsServerNotFound","errorMessage":"metrics server not found","messagePattern":"metrics server not found","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"diagnostic/error.go","lineNumber":23,"sourceCode":")\n\nvar (\n\t// Error used when there is no log directory available.\n\tErrManagedLogNotFound = errors.New(\"managed log directory not found\")\n\t// Error used when it is not possible to collect logs using the log configuration.\n\tErrLogConfigurationIsInvalid = errors.New(\"provided log configuration is invalid\")\n\t// Error used when parsing the fields of the output of collector.\n\tErrInsufficientLines = errors.New(\"insufficient lines\")\n\t// Error used when parsing the lines of the output of collector.\n\tErrInsuficientFields = errors.New(\"insufficient fields\")\n\t// Error used when given key is not found while parsing KV.\n\tErrKeyNotFound = errors.New(\"key not found\")\n\t// Error used when there is no disk volume information available.\n\tErrNoVolumeFound = errors.New(\"no disk volume information found\")\n\t// Error user when the base url of the diagnostic client is not provided.\n\tErrNoBaseURL = errors.New(\"no base url\")\n\t// Error used when no metrics server is found listening to the known addresses list (check [metrics.GetMetricsKnownAddresses]).\n\tErrMetricsServerNotFound = errors.New(\"metrics server not found\")\n\t// Error used when multiple metrics server are found listening to the known addresses list (check [metrics.GetMetricsKnownAddresses]).\n\tErrMultipleMetricsServerFound = errors.New(\"multiple metrics server found\")\n\t// Error used when a temporary file creation fails within the diagnostic procedure\n\tErrCreatingTemporaryFile = errors.New(\"temporary file creation failed\")\n)\n","sourceCodeStart":5,"sourceCodeEnd":29,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/diagnostic/error.go#L5-L29","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start a cloudflared tunnel instance and confirm its metrics server is listening before running diagnostics.","Check the tunnel's log to confirm the actual metrics address; pass a matching address if a custom --metrics port is used.","Handle errors.Is(err, diagnostic.ErrMetricsServerNotFound) gracefully as the CLI does — warn and exit 0.","Verify the process is running under the same user/namespace so its metrics port is reachable."],"exampleFix":"states, err := diagnostic.RunDiagnostic(log, options)\nif errors.Is(err, diagnostic.ErrMetricsServerNotFound) {\n\tlog.Warn().Msg(\"No instances found\")\n\treturn nil\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"states, err := diagnostic.RunDiagnostic(log, options)\nif errors.Is(err, diagnostic.ErrMetricsServerNotFound) {\n\tlog.Warn().Msg(\"No instances found\")\n\treturn nil\n}","preventionTips":["Start/verify the tunnel process before invoking diagnostic commands.","Confirm the metrics listener address matches the known addresses list (custom --metrics ports must be discoverable).","Check process liveness (pid) as a pre-flight before running diagnostics."],"tags":["metrics","diagnostic","process-discovery"],"backgroundTag":"resource-not-found","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}