opentofu/opentofu · error

from %q credential helper: %w

Error message

from %q credential helper: %w

What it means

A Docker credential helper source (from a 'credHelpers' entry, an 'auths' credHelpers mapping, a default_docker_credential_helper, or an explicit docker_credential_helper argument) tried to obtain credentials by querying the helper program for serverURL 'https://<registryDomain>' and the helper interaction failed. The wrapped error from QueryDockerCredentialHelper carries the actual cause: helper missing, helper crash, or 'credentials not found' for that server.

Source

Thrown at internal/command/cliconfig/ociauthconfig/credentials_source.go:66

func (s *staticCredentialsSource) credentialsSourceImpl() {}

type dockerCredentialHelperCredentialSource struct {
	helperName string
	serverURL  string
	spec       CredentialsSpecificity
}

var _ CredentialsSource = (*dockerCredentialHelperCredentialSource)(nil)

func (s *dockerCredentialHelperCredentialSource) CredentialsSpecificity() CredentialsSpecificity {
	return s.spec
}

func (s *dockerCredentialHelperCredentialSource) Credentials(ctx context.Context, env CredentialsLookupEnvironment) (Credentials, error) {
	result, err := env.QueryDockerCredentialHelper(ctx, s.helperName, s.serverURL)
	if err != nil {
		return Credentials{}, fmt.Errorf("from %q credential helper: %w", s.helperName, err)
	}
	return Credentials{
		username: result.Username,
		password: result.Secret,
		// Docker-style credential helpers cannot produce OAuth credentials
	}, nil
}

func (s *dockerCredentialHelperCredentialSource) credentialsSourceImpl() {}

View on GitHub (pinned to 3561785c48)

Solutions

1. Read the wrapped message: 'not found' vs 'exec: not found' vs a helper-specific message point to different fixes
2. Install the missing helper binary (e.g. docker-credential-pass, docker-credential-desktop) and ensure it is on PATH
3. Re-authenticate: docker login <registry> to refresh what the helper stores
4. Remove the stale 'credsStore'/'credHelpers' entry from the Docker config if that helper is gone
5. Use 'docker-credential-<name> list' to confirm the server URL the helper actually knows about

creds, err := source.Credentials(ctx, env)
if err != nil {
    if ociauthconfig.IsCredentialsNotFoundError(err) {
        // helper has no credentials for this server: not a fault
    } else if strings.Contains(err.Error(), "credential helper") {
        // helper-level failure: check wrapped cause (missing binary vs auth failure)
    }
}

When it happens

Trigger: env.QueryDockerCredentialHelper returns an error: the docker-credential-* binary is not installed/not on PATH, the helper exits non-zero, or it reports no credentials for https://<domain>. Any of these is wrapped as 'from "<helperName>" credential helper: ...'.

Common situations: config.json references docker-credential-desktop or docker-credential-wincred on a machine without Docker Desktop; helper config copied between OSes; expired helper credentials in CI; 'credsStore' entry pointing at a helper that was uninstalled.

Related errors

• discovering ambient OCI registry credentials: %w
• failed to read Docker-style config files: %w
• from %s: %w
• reading %s: %w
• parsing %s: %w

AI-assisted analysis of opentofu/opentofu@3561785c48 (2026-08-15). Data as JSON: /api/errors/a3e7ca0774a9f492. Report an issue: GitHub.