DOCKER_AUTH_CONFIG environment variable is missing key…

Error message

DOCKER_AUTH_CONFIG environment variable is missing key `auth` for %s

What it means

Raised by parseEnvConfig (file.go:366-367) when parsing the DOCKER_AUTH_CONFIG environment variable. The env JSON is decoded into a struct whose `auths.<addr>` entries each must contain an `auth` field; if any entry omits it, this error names the registry address. The `auth` value must be base64 of `username:password`.

Solutions

Reconstruct the env var using the expected schema: `{"auths":{"<registry>":{"auth":"<base64(user:pass)>"}}}`.
Generate the base64 with `printf '%s' "$USER:$PASS" | base64`.
Remove DOCKER_AUTH_CONFIG and use `docker login` / a credential helper if the env format is hard to maintain.
Validate the JSON with `echo "$DOCKER_AUTH_CONFIG" | jq .` before exporting it.

Example fix

# before
export DOCKER_AUTH_CONFIG='{"auths":{"myreg.io":{"username":"u","password":"p"}}}'
# after
AUTH=$(printf '%s' 'u:p' | base64)
export DOCKER_AUTH_CONFIG="{\"auths\":{\"myreg.io\":{\"auth\":\"$AUTH\"}}}"

Defensive patterns

Strategy: validation

Validate before calling

// Validate DOCKER_AUTH_CONFIG shape before any docker call.
func validateDockerAuthConfig(v string) error {
    var c struct {
        Auths map[string]struct{ Auth string `json:"auth"` } `json:"auths"`
    }
    dec := json.NewDecoder(strings.NewReader(v))
    dec.DisallowUnknownFields()
    if err := dec.Decode(&c); err != nil {
        return err
    }
    for addr, a := range c.Auths {
        if a.Auth == "" {
            return fmt.Errorf("missing auth for %s", addr)
        }
    }
    return nil
}

Try / catch

// Docker prints a warning and falls back; detect via stderr or pre-validate.
if err := validateDockerAuthConfig(os.Getenv("DOCKER_AUTH_CONFIG")); err != nil {
    log.Fatalf("DOCKER_AUTH_CONFIG invalid: %v", err)
}

Prevention

Generate DOCKER_AUTH_CONFIG with `printf '%s' "$USER:$PASS" | base64`.
Validate with `echo "$DOCKER_AUTH_CONFIG" | jq .` in CI.
Prefer `docker login` over the env var when possible.

When it happens

Trigger: GetCredentialsStore reads DOCKER_AUTH_CONFIG, parseEnvConfig decodes the JSON, and for some `auths.<addr>` the `Auth` string is empty. This happens when the env var provides a username/password directly or only a registry address without the `auth` base64 blob.

Common situations: A CI/CD pipeline sets DOCKER_AUTH_CONFIG with a structure like `{"auths":{"myregistry.com":{}}}` or with `username`/`password` keys (which are unsupported) instead of the expected `{"auths":{"myregistry.com":{"auth":"<base64>"}}}`. Copy-pasting a registry secret that omits the auth field also triggers it.

Related errors

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

Appendix: source

Thrown at cli/config/configfile/file.go:367

	return envStore
}

func parseEnvConfig(v string) (map[string]types.AuthConfig, error) {
	envConfig := &configEnv{}
	decoder := json.NewDecoder(strings.NewReader(v))
	decoder.DisallowUnknownFields()
	if err := decoder.Decode(envConfig); err != nil && !errors.Is(err, io.EOF) {
		return nil, err
	}
	if decoder.More() {
		return nil, errors.New("DOCKER_AUTH_CONFIG does not support more than one JSON object")
	}

	authConfigs := make(map[string]types.AuthConfig)
	for addr, envAuth := range envConfig.AuthConfigs {
		if envAuth.Auth == "" {
			return nil, fmt.Errorf("DOCKER_AUTH_CONFIG environment variable is missing key `auth` for %s", addr)
		}
		username, password, err := decodeAuth(envAuth.Auth)
		if err != nil {
			return nil, err
		}
		authConfigs[addr] = types.AuthConfig{
			Username:      username,
			Password:      password,
			ServerAddress: addr,
		}
	}
	return authConfigs, nil
}

// var for unit testing.
var newNativeStore = func(configFile *ConfigFile, helperSuffix string) credentials.Store {
	return credentials.NewNativeStore(configFile, helperSuffix)
}

View on GitHub (pinned to 4f84911bfe)