{"record":{"id":"a68e0133de09f72f","repo":"docker/cli","slug":"docker-auth-config-environment-variable-is-missing","errorCode":null,"errorMessage":"DOCKER_AUTH_CONFIG environment variable is missing key `auth` for %s","messagePattern":"DOCKER_AUTH_CONFIG environment variable is missing key `auth` for (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/config/configfile/file.go","lineNumber":367,"sourceCode":"\n\treturn envStore\n}\n\nfunc parseEnvConfig(v string) (map[string]types.AuthConfig, error) {\n\tenvConfig := &configEnv{}\n\tdecoder := json.NewDecoder(strings.NewReader(v))\n\tdecoder.DisallowUnknownFields()\n\tif err := decoder.Decode(envConfig); err != nil && !errors.Is(err, io.EOF) {\n\t\treturn nil, err\n\t}\n\tif decoder.More() {\n\t\treturn nil, errors.New(\"DOCKER_AUTH_CONFIG does not support more than one JSON object\")\n\t}\n\n\tauthConfigs := make(map[string]types.AuthConfig)\n\tfor addr, envAuth := range envConfig.AuthConfigs {\n\t\tif envAuth.Auth == \"\" {\n\t\t\treturn nil, fmt.Errorf(\"DOCKER_AUTH_CONFIG environment variable is missing key `auth` for %s\", addr)\n\t\t}\n\t\tusername, password, err := decodeAuth(envAuth.Auth)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tauthConfigs[addr] = types.AuthConfig{\n\t\t\tUsername:      username,\n\t\t\tPassword:      password,\n\t\t\tServerAddress: addr,\n\t\t}\n\t}\n\treturn authConfigs, nil\n}\n\n// var for unit testing.\nvar newNativeStore = func(configFile *ConfigFile, helperSuffix string) credentials.Store {\n\treturn credentials.NewNativeStore(configFile, helperSuffix)\n}","sourceCodeStart":349,"sourceCodeEnd":385,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/config/configfile/file.go#L349-L385","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nexport DOCKER_AUTH_CONFIG='{\"auths\":{\"myreg.io\":{\"username\":\"u\",\"password\":\"p\"}}}'\n# after\nAUTH=$(printf '%s' 'u:p' | base64)\nexport DOCKER_AUTH_CONFIG=\"{\\\"auths\\\":{\\\"myreg.io\\\":{\\\"auth\\\":\\\"$AUTH\\\"}}}\"","handlingStrategy":"validation","validationCode":"// Validate DOCKER_AUTH_CONFIG shape before any docker call.\nfunc validateDockerAuthConfig(v string) error {\n    var c struct {\n        Auths map[string]struct{ Auth string `json:\"auth\"` } `json:\"auths\"`\n    }\n    dec := json.NewDecoder(strings.NewReader(v))\n    dec.DisallowUnknownFields()\n    if err := dec.Decode(&c); err != nil {\n        return err\n    }\n    for addr, a := range c.Auths {\n        if a.Auth == \"\" {\n            return fmt.Errorf(\"missing auth for %s\", addr)\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"// Docker prints a warning and falls back; detect via stderr or pre-validate.\nif err := validateDockerAuthConfig(os.Getenv(\"DOCKER_AUTH_CONFIG\")); err != nil {\n    log.Fatalf(\"DOCKER_AUTH_CONFIG invalid: %v\", err)\n}","preventionTips":["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."],"tags":["config","auth","environment","docker-auth-config","credentials"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}