docker/compose · error

resolving credentials failed: %w

Error message

resolving credentials failed: %w

What it means

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.

Source

Thrown at pkg/compose/apiSocket.go:50

func (s *composeService) useAPISocket(project *types.Project) (*types.Project, error) {
	useAPISocket := false
	for _, service := range project.Services {
		if service.UseAPISocket {
			useAPISocket = true
			break
		}
	}
	if !useAPISocket {
		return project, nil
	}

	if s.getContextInfo().ServerOSType() == "windows" {
		return nil, errors.New("use_api_socket can't be used with a Windows Docker Engine")
	}

	creds, err := s.configFile().GetAllCredentials()
	if err != nil {
		return nil, fmt.Errorf("resolving credentials failed: %w", err)
	}

	newConfig := &configfile.ConfigFile{
		AuthConfigs: creds,
	}
	var configBuf bytes.Buffer
	if err := newConfig.SaveToWriter(&configBuf); err != nil {
		return nil, fmt.Errorf("saving creds for API socket: %w", err)
	}

	project.Configs["#apisocket"] = types.ConfigObjConfig{
		Content: configBuf.String(),
	}

	for name, service := range project.Services {
		if !service.UseAPISocket {
			continue
		}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Run docker login (or a plain credentials round-trip) to confirm the credential store works outside compose
2. Inspect ~/.docker/config.json: verify the credsStore/credHelpers value names an installed helper (docker-credential-<name> on PATH)
3. Install/reconfigure the helper (e.g. docker-credential-pass with a working gpg agent) or temporarily remove the credsStore key to test
4. Disable use_api_socket on the service if mounting the API socket with host creds is not required

Example fix

# before (~/.docker/config.json)
{ "credsStore": "pass" }   # pass helper broken / not initialized
# after
{ "credsStore": "desktop" }  # or remove the key after verifying with: docker-credential-pass list

// Before up with use_api_socket services:
for name, svc := range project.Services {
	if !svc.UseAPISocket {
		continue
	}
	if _, err := dockerCli.ConfigFile().GetAllCredentials(); err != nil {
		return fmt.Errorf("credential store unusable (service %s uses use_api_socket): %w", name, err)
	}
}

if err := compose.Up(ctx, project, api.UpOptions{}); err != nil {
	if strings.Contains(err.Error(), "resolving credentials failed") {
		// fix ~/.docker/config.json credential helper, then docker login, then retry
	}
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• saving creds for API socket: %w
• use_api_socket can't be used with a Windows Docker Engine
• failed to access repository at %s: %s
• failed to pull OCI resource %q: %w

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/9556e039869e9317. Report an issue: GitHub.