docker/cli · error

unrecognized config key: ${k}

Error message

unrecognized config key: ${k}

What it means

When creating/updating a context, validateConfig() rejects any "docker." configuration key not present in the allowedDockerConfigKeys allow-list (from, host, ca, cert, key, skip-tls-verify). All offending keys are collected and joined via errors.Join, so a single run reports every bad key at once.

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 4f84911bfe)

Solutions

1. Use only allowed keys: from, host, ca, cert, key, skip-tls-verify
2. Check `docker context create --help` for the documented set
3. Fix the typo in the offending key reported in the message

Example fix

// before
docker context create myctx --docker tls=/etc/certs/ca.pem
// after
docker context create myctx --docker ca=/etc/certs/ca.pem

var allowedDockerConfigKeys = map[string]struct{}{
    "from": {}, "host": {}, "ca": {}, "cert": {}, "key": {}, "skip-tls-verify": {},
}
func isValidConfigKey(k string) bool {
    _, ok := allowedDockerConfigKeys[k]
    return ok
}
// before create: for k := range config { if !isValidConfigKey(k) { return error } }

func isAllowedDockerConfigKey(k string) bool {
    switch k {
    case "from", "host", "ca", "cert", "key", "skip-tls-verify":
        return true
    }
    return false
}

When it happens

Trigger: Running `docker context create myctx --docker typo=val` where "typo" is not one of the six allowed keys; the offending key name is interpolated into the message.

Common situations: A typo'd key (e.g. "tls" instead of "ca"); outdated documentation examples using retired key names; copy-pasting from a non-Docker tool's syntax.

Related errors

• no context specified
• invalid key/value pair format in driver options
• invalid field '%s' must be a key=value pair
• invalid mode specified: %v
• invalid field in config request: %s

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/c89f40a5107a323e. Report an issue: GitHub.