docker/cli · error

unrecognized config key:

Error message

unrecognized config key: 

What it means

Context endpoint specs passed via --docker (and --kubernetes historically) are comma-separated key=value maps. validateConfig checks every provided key against an allowlist (for docker: host, ca, cert, key, skip-tls-verify, from) and joins an 'unrecognized config key: <k>' error for each unknown key. This catches typos and unsupported options before a broken context is persisted.

Source

Thrown at cli/command/context/options.go:85

	if !ok {
		return false, nil
	}
	res, err := strconv.ParseBool(strVal)
	if err != nil {
		var nErr *strconv.NumError
		if errors.As(err, &nErr) {
			return res, fmt.Errorf("%s: parsing %q: %w", name, nErr.Num, nErr.Err)
		}
		return res, fmt.Errorf("%s: %w", name, err)
	}
	return res, nil
}

func validateConfig(config map[string]string, allowedKeys map[string]struct{}) error {
	var errs []error
	for k := range config {
		if _, ok := allowedKeys[k]; !ok {
			errs = append(errs, errors.New("unrecognized config key: "+k))
		}
	}
	return errors.Join(errs...)
}

func getDockerEndpoint(contextStore store.Reader, config map[string]string) (docker.Endpoint, error) {
	if err := validateConfig(config, allowedDockerConfigKeys); err != nil {
		return docker.Endpoint{}, err
	}
	if contextName, ok := config[keyFrom]; ok {
		metadata, err := contextStore.GetMetadata(contextName)
		if err != nil {
			return docker.Endpoint{}, err
		}
		if ep, ok := metadata.Endpoints[docker.DockerEndpoint].(docker.EndpointMeta); ok {
			return docker.Endpoint{EndpointMeta: ep}, nil
		}
		return docker.Endpoint{}, fmt.Errorf("unable to get endpoint from context %q", contextName)

View on GitHub (pinned to e9452d6e78)

Solutions

1. Fix the key name — valid docker endpoint keys are: host, ca, cert, key, skip-tls-verify, from.
2. Quote the whole spec so commas/equals survive the shell: `--docker "host=tcp://1.2.3.4:2376,skip-tls-verify=true"`.
3. For TLS material use ca=/cert=/key= file paths, not daemon-style tlscacert/tlscert flags.

Example fix

# before
docker context create remote --docker "hosts=tcp://1.2.3.4:2376,tls=true"
# after
docker context create remote --docker "host=tcp://1.2.3.4:2376,skip-tls-verify=true"

When it happens

Trigger: `docker context create`/`update` with a --docker spec containing a key outside the allowlist, e.g. `--docker "hosts=tcp://..."`, `--docker "tls=true"`, or quoting mistakes that make the whole string one key (`--docker host tcp://...`). Each bad key produces one error entry via cli/command/context/options.go:85.

Common situations: Typos like hosts/hostname instead of host, tlsverify/tls instead of skip-tls-verify; confusing daemon.json or DOCKER_HOST option names with context config keys; unquoted specs where the shell splits on spaces or = producing garbage keys.

Related errors

• conflicting options: cannot specify both --host and --contex
• docker endpoint configuration is required
• no context specified
• plugin candidate path cannot be empty
• plugin SchemaVersion version cannot be empty

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/450df49d56cac3d8.json. Report an issue: GitHub.