docker/cli · error

failed to read credentials from DOCKER_AUTH_CONFIG

Error message

failed to read credentials from DOCKER_AUTH_CONFIG: %w

What it means

Returned by readCredentials() when DOCKER_AUTH_CONFIG is set but cannot be parsed into a configfile.ConfigFile (cli/command/container/auth_config_utils.go:31-34). LoadFromReader expects the same JSON format as ~/.docker/config.json (with an 'auths' map); any JSON syntax error or structurally invalid document fails here and is wrapped with this message.

Solutions

1. Format DOCKER_AUTH_CONFIG as a full config.json document: {"auths":{"registry.example.com":{"auth":"<base64(user:pass)>"}}}.
2. Validate the JSON before exporting: echo "$DOCKER_AUTH_CONFIG" | jq . (or python -m json.tool).
3. Generate the base64 token correctly: printf '%s' 'user:pass' | base64.
4. If you only need the credentials store, unset DOCKER_AUTH_CONFIG to fall through to it.

Example fix

# before
export DOCKER_AUTH_CONFIG='user:pass'   # not valid JSON
# after
TOKEN=$(printf '%s' 'user:pass' | base64)
export DOCKER_AUTH_CONFIG='{"auths":{"registry.example.com":{"auth":"'$TOKEN'"}}}'

// Validate DOCKER_AUTH_CONFIG is a well-formed config.json document.
func validateAuthConfigEnv(value string) error {
    var cfg struct{ Auths map[string]json.RawMessage }
    if err := json.Unmarshal([]byte(value), &cfg); err != nil {
        return fmt.Errorf("DOCKER_AUTH_CONFIG must be JSON like {\"auths\":{...}}: %w", err)
    }
    return nil
}

When it happens

Trigger: Setting DOCKER_AUTH_CONFIG to a malformed JSON document (missing braces, trailing comma, wrong structure) while using --use-api-socket on docker create/run. The env var is consumed only on that code path; a parse failure aborts credential resolution before container creation.

Common situations: Hand-crafted DOCKER_AUTH_CONFIG with a typo, a value that is base64 credentials pasted directly instead of wrapped in the {"auths":{...}} structure, or copy-paste truncation. Note the whole document must be valid JSON, not just a base64 blob.

Related errors

• resolving credentials failed
• resolving credentials failed
• DOCKER_BUILDKIT environment variable expects boolean value
• failed to parse custom headers from
• failed to set custom headers from

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

Appendix: source

Thrown at cli/command/container/auth_config_utils.go:33

//
//   - If a valid "DOCKER_AUTH_CONFIG" env-var is found, and it contains
//     credentials, it's value is used.
//   - If no "DOCKER_AUTH_CONFIG" env-var is found, or it does not contain
//     credentials, it attempts to read from the CLI's credentials store.
//
// It returns an error if either the "DOCKER_AUTH_CONFIG" is incorrectly
// formatted, or when failing to read from the credentials store.
//
// A nil value is returned if neither option contained any credentials.
func readCredentials(dockerCLI config.Provider) (creds map[string]types.AuthConfig, _ error) {
	if v, ok := os.LookupEnv("DOCKER_AUTH_CONFIG"); ok && v != "" {
		// The results are expected to have been unmarshaled the same as
		// when reading from a config-file, which includes decoding the
		// base64-encoded "username:password" into the "UserName" and
		// "Password" fields.
		ac := &configfile.ConfigFile{}
		if err := ac.LoadFromReader(strings.NewReader(v)); err != nil {
			return nil, fmt.Errorf("failed to read credentials from DOCKER_AUTH_CONFIG: %w", err)
		}
		if len(ac.AuthConfigs) > 0 {
			return ac.AuthConfigs, nil
		}
	}

	// Resolve this here for later, ensuring we error our before we create the container.
	creds, err := dockerCLI.ConfigFile().GetAllCredentials()
	if err != nil {
		return nil, fmt.Errorf("resolving credentials failed: %w", err)
	}
	return creds, nil
}

View on GitHub (pinned to 4f84911bfe)