docker/cli · error

resolving credentials failed

Error message

resolving credentials failed: %w

What it means

Returned by readCredentials() when DOCKER_AUTH_CONFIG is absent/empty and the fallback call to dockerCLI.ConfigFile().GetAllCredentials() fails (cli/command/container/auth_config_utils.go:41-44). GetAllCredentials walks all configured auth entries and may consult the OS credential helper (pass, wincred, osxkeychain, secretservice); a helper invocation failure or a corrupt config.json auth section surfaces here.

Solutions

1. Verify the configured credential helper is installed and functional: docker-credential-<name> list should succeed.
2. For 'pass', ensure the GPG key and password store are initialized (gpg --list-keys, pass init <keyid>).
3. Inspect ~/.docker/config.json for a credsStore value pointing at a missing helper, and install or unset it.
4. If you intend to supply creds directly, set DOCKER_AUTH_CONFIG to bypass the local store.

Example fix

# before
# config.json has "credsStore":"pass" but pass/GPG not initialized -> GetAllCredentials fails
# after
pass init <gpg-key-id>
# or remove the helper:
# edit ~/.docker/config.json -> remove credsStore, restart shell

// Verify the configured credential helper responds before relying on it.
func validateCredsHelper(store string) error {
    cmd := exec.Command("docker-credential-"+store, "list")
    if err := cmd.Run(); err != nil {
        return fmt.Errorf("credential helper %q not functional: %w", store, err)
    }
    return nil
}

creds, err := dockerCLI.ConfigFile().GetAllCredentials()
if err != nil {
    // hint: check credsStore in ~/.docker/config.json, install/initialize the helper
}

When it happens

Trigger: Using --use-api-socket on docker create/run without DOCKER_AUTH_CONFIG, where the local credential store cannot be read: the configured credsStore helper binary is missing/non-functional, returns an error, or an auths entry is malformed.

Common situations: credsStore set to 'pass'/'osxkeychain'/'secretservice' but the helper is not installed or not initialized; config.json references a helper that errors; GPG/pass backend locked or misconfigured; corrupted ~/.docker/config.json.

Related errors

• failed to read credentials from DOCKER_AUTH_CONFIG
• resolving credentials failed
• error establishing connection to trust repository
• failed to parse hook template
• plugin SchemaVersion version cannot be empty

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

Appendix: source

Thrown at cli/command/container/auth_config_utils.go:43

func readCredentials(dockerCLI config.Provider) (creds map[string]types.AuthConfig, _ error) {
	if v, ok := os.LookupEnv("DOCKER_AUTH_CONFIG"); ok && v != "" {
		// The results are expected to have been unmarshaled the same as
		// when reading from a config-file, which includes decoding the
		// base64-encoded "username:password" into the "UserName" and
		// "Password" fields.
		ac := &configfile.ConfigFile{}
		if err := ac.LoadFromReader(strings.NewReader(v)); err != nil {
			return nil, fmt.Errorf("failed to read credentials from DOCKER_AUTH_CONFIG: %w", err)
		}
		if len(ac.AuthConfigs) > 0 {
			return ac.AuthConfigs, nil
		}
	}

	// Resolve this here for later, ensuring we error our before we create the container.
	creds, err := dockerCLI.ConfigFile().GetAllCredentials()
	if err != nil {
		return nil, fmt.Errorf("resolving credentials failed: %w", err)
	}
	return creds, nil
}

View on GitHub (pinned to 4f84911bfe)