{"record":{"id":"14402128f38d5926","repo":"cloudflare/cloudflared","slug":"errkeynotfound","errorCode":"ErrKeyNotFound","errorMessage":"key not found","messagePattern":"key not found","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"diagnostic/error.go","lineNumber":17,"sourceCode":"package diagnostic\n\nimport (\n\t\"errors\"\n)\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":1,"sourceCodeEnd":29,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/diagnostic/error.go#L1-L29","documentation":"ErrKeyNotFound is the sentinel error in diagnostic/error.go used when a required key is absent while parsing key/value output. Several parsers return it (optionally wrapped with the missing key name): GetLogConfiguration when the configuration UID key is missing (diagnostic/client.go:81), ParseWinOperatingSystemInfo, ParseFileDescriptorInformationFromKV, and ParseMemoryInformationFromKV, plus OS-information parsing where e.g. the architecture key is absent (system_collector_utils.go:182). It means the collector output was parseable as KV but lacked an expected key.","triggerScenarios":"Calling diagnostic.HttpClient-based collectors such as GetLogConfiguration where `data[configurationKeyUID]` is missing (client.go:81); ParseFileDescriptorInformationFromKV and ParseMemoryInformationFromKV when the collector's KV output omits required keys; ParseWinOperatingSystemInfo on Windows output missing OS keys; OS information parsing when `pairs[architectureKey]` does not exist (system_collector_utils.go:182), producing `parsing os information: %w, key=%s`.","commonSituations":"Remote (HTTP) diagnostics against a container or older cloudflared instance whose diagnostic endpoint returns an older/newer KV schema missing keys like UID or architecture; cross-version collection where the client expects keys the server does not emit; partially failing system commands that emit KV output with some keys absent.","solutions":["Ensure the remote instance runs a cloudflared version whose diagnostic output schema matches the client's expectations; upgrade the target instance (or the client) so both sides agree on keys.","Re-run diagnostics with the correct environment targeting (--diag-container-id / --diag-pod-id) so the collector queries an endpoint that actually produces the expected KV keys.","Read the wrapped key name in the error message (`key=...`) and check why that specific value is missing in the target environment (e.g. architecture detection failing on exotic platforms).","Enable debug logging and capture the raw collector response to compare emitted keys against expected ones, then fix the environment or report a schema mismatch."],"exampleFix":"// before: client expects UID key from an older remote instance\ncloudflared diag --output out.zip  // remote returns KV without UID -> ErrKeyNotFound\n\n// after: upgrade the remote cloudflared first\nssh host 'cloudflared update && systemctl restart cloudflared'\ncloudflared diag --output out.zip","handlingStrategy":"try-catch","validationCode":"// Go: confirm required keys exist in the KV map before use\nrequired := []string{\"uid\", \"architecture\"}\nfor _, k := range required {\n    if _, ok := kv[k]; !ok {\n        // key missing; abort parse early\n    }\n}","typeGuard":"func requireKeys(data map[string]string, keys ...string) (missing []string) {\n    for _, k := range keys {\n        if _, ok := data[k]; !ok {\n            missing = append(missing, k)\n        }\n    }\n    return\n}","tryCatchPattern":"cfg, err := client.GetLogConfiguration(ctx)\nif errors.Is(err, diagnostic.ErrKeyNotFound) {\n    log.Warn().Msg(\"collector KV output missing expected key; check cloudflared version on target\")\n    return nil\n}","preventionTips":["Keep client and remote cloudflared versions aligned so the KV schema matches.","Unwrap the error to read the missing key name and fix that value's source in the environment.","Validate KV responses against an expected key set before consuming them.","Use --diag-container-id/--diag-pod-id so collection hits an endpoint emitting the full key set."],"tags":["diagnostics","parsing","key-value","cloudflared"],"backgroundTag":"missing-config-key","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"}