{"record":{"id":"9556e039869e9317","repo":"docker/compose","slug":"resolving-credentials-failed-w","errorCode":null,"errorMessage":"resolving credentials failed: %w","messagePattern":"resolving credentials failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/apiSocket.go","lineNumber":50,"sourceCode":"func (s *composeService) useAPISocket(project *types.Project) (*types.Project, error) {\n\tuseAPISocket := false\n\tfor _, service := range project.Services {\n\t\tif service.UseAPISocket {\n\t\t\tuseAPISocket = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif !useAPISocket {\n\t\treturn project, nil\n\t}\n\n\tif s.getContextInfo().ServerOSType() == \"windows\" {\n\t\treturn nil, errors.New(\"use_api_socket can't be used with a Windows Docker Engine\")\n\t}\n\n\tcreds, err := s.configFile().GetAllCredentials()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"resolving credentials failed: %w\", err)\n\t}\n\n\tnewConfig := &configfile.ConfigFile{\n\t\tAuthConfigs: creds,\n\t}\n\tvar configBuf bytes.Buffer\n\tif err := newConfig.SaveToWriter(&configBuf); err != nil {\n\t\treturn nil, fmt.Errorf(\"saving creds for API socket: %w\", err)\n\t}\n\n\tproject.Configs[\"#apisocket\"] = types.ConfigObjConfig{\n\t\tContent: configBuf.String(),\n\t}\n\n\tfor name, service := range project.Services {\n\t\tif !service.UseAPISocket {\n\t\t\tcontinue\n\t\t}","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/apiSocket.go#L32-L68","documentation":"When a service uses use_api_socket: true (exposing the Docker API socket to the container), compose serializes the host's registry credentials into an in-file config so the container can authenticate. It collects them with configFile().GetAllCredentials(); this error wraps a failure of that collection. The underlying cause is a malformed credentials store entry or a broken credentials-store helper (desktop, pass, wincred...) configured in ~/.docker/config.json.","triggerScenarios":"A project with any service having use_api_socket: true while config.json declares a credsStore or credHelpers entry whose binary is missing, not executable, or returns invalid JSON; a corrupted entry in the credential store; registry auth JSON in config.json that cannot be base64-decoded.","commonSituations":"Docker Desktop credential helper not installed or broken on Linux (pass without GPG setup); a config.json copied between machines pointing at a helper that does not exist there; expired/corrupted pass entries; switching between credential stores without cleaning old entries.","solutions":["Run docker login (or a plain credentials round-trip) to confirm the credential store works outside compose","Inspect ~/.docker/config.json: verify the credsStore/credHelpers value names an installed helper (docker-credential-<name> on PATH)","Install/reconfigure the helper (e.g. docker-credential-pass with a working gpg agent) or temporarily remove the credsStore key to test","Disable use_api_socket on the service if mounting the API socket with host creds is not required"],"exampleFix":"# before (~/.docker/config.json)\n{ \"credsStore\": \"pass\" }   # pass helper broken / not initialized\n# after\n{ \"credsStore\": \"desktop\" }  # or remove the key after verifying with: docker-credential-pass list\n","handlingStrategy":"validation","validationCode":"// Before up with use_api_socket services:\nfor name, svc := range project.Services {\n\tif !svc.UseAPISocket {\n\t\tcontinue\n\t}\n\tif _, err := dockerCli.ConfigFile().GetAllCredentials(); err != nil {\n\t\treturn fmt.Errorf(\"credential store unusable (service %s uses use_api_socket): %w\", name, err)\n\t}\n}","typeGuard":null,"tryCatchPattern":"if err := compose.Up(ctx, project, api.UpOptions{}); err != nil {\n\tif strings.Contains(err.Error(), \"resolving credentials failed\") {\n\t\t// fix ~/.docker/config.json credential helper, then docker login, then retry\n\t}\n}","preventionTips":["Verify the credential helper works after any docker/Docker Desktop upgrade (docker-credential-<store> list)","Avoid copying ~/.docker/config.json between machines with different helpers installed","Only enable use_api_socket on services that truly need the host API socket"],"tags":["credentials","docker-config","api-socket","authentication"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}