cloudflare/cloudflared · warning

ErrKeyNotFound

ErrKeyNotFound

Error message

key not found

What it means

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.

Source

Thrown at diagnostic/error.go:17

package diagnostic

import (
	"errors"
)

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. 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.
2. 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.
3. 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).
4. 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.

Example fix

// before: client expects UID key from an older remote instance
cloudflared diag --output out.zip  // remote returns KV without UID -> ErrKeyNotFound

// after: upgrade the remote cloudflared first
ssh host 'cloudflared update && systemctl restart cloudflared'
cloudflared diag --output out.zip

// Go: confirm required keys exist in the KV map before use
required := []string{"uid", "architecture"}
for _, k := range required {
    if _, ok := kv[k]; !ok {
        // key missing; abort parse early
    }
}

func requireKeys(data map[string]string, keys ...string) (missing []string) {
    for _, k := range keys {
        if _, ok := data[k]; !ok {
            missing = append(missing, k)
        }
    }
    return
}

cfg, err := client.GetLogConfiguration(ctx)
if errors.Is(err, diagnostic.ErrKeyNotFound) {
    log.Warn().Msg("collector KV output missing expected key; check cloudflared version on target")
    return nil
}

When it happens

Trigger: 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`.

Common situations: 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.

Related errors

• ErrInsufficientLines
• ErrInsuficientFields
• ErrManagedLogNotFound
• ErrLogConfigurationIsInvalid
• ErrEmptyDomain

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