docker/compose · error

saving creds for API socket: %w

Error message

saving creds for API socket: %w

What it means

Continuing the use_api_socket flow: after credentials are collected, they are written into an in-memory docker config via newConfig.SaveToWriter so they can be embedded as a project config. This error wraps SaveToWriter failing — almost always because an individual credential (username/password/token) contains data that cannot be serialized into the auth JSON, or because GetAllCredentials returned entries with unusable values.

Source

Thrown at pkg/compose/apiSocket.go:58

	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
		}
		service.Volumes = append(service.Volumes, types.ServiceVolumeConfig{
			Type:   types.VolumeTypeBind,
			Source: "/var/run/docker.sock",
			Target: "/var/run/docker.sock",
		})

		_, envvarPresent := service.Environment["DOCKER_CONFIG"]

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Inspect ~/.docker/config.json auths/credHelpers entries for malformed values and remove stale ones
2. Re-do docker login against the affected registry to rewrite a clean entry
3. Switch to a standard credential store (desktop/pass/secretservice) temporarily to isolate the failing helper
4. Disable use_api_socket if the feature is not strictly needed

Example fix

# before: stale malformed entry
"auths": { "https://old-registry.example": { "auth": "not-base64!!" } }
# after: remove and re-login
$ jq 'del(.auths["https://old-registry.example"])' ~/.docker/config.json > tmp && mv tmp ~/.docker/config.json
$ docker login old-registry.example

if err := compose.Up(ctx, project, api.UpOptions{}); err != nil {
	if strings.Contains(err.Error(), "saving creds for API socket") {
		// a specific credential entry failed to serialize: prune auths entries and docker login again
		return errors.Join(err, fixCredsHint())
	}
	return err
}

When it happens

Trigger: A credential entry containing invalid UTF-8 or structurally invalid auth data that JSON-encodes/decodes badly; identity tokens or registry-specific helpers producing entries that do not fit the AuthConfigs schema.

Common situations: Rare; seen with exotic credential helpers or manually edited ~/.docker/config.json auths entries; occasionally after a Docker Desktop credential migration that leaves half-written entries.

Related errors

• resolving credentials failed: %w
• use_api_socket can't be used with a Windows Docker Engine
• cannot render project into yaml: %w
• 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/ba8c8e3e986de954. Report an issue: GitHub.