What causes "discovering ambient OCI registry credentials: %w" in opentofu/opentofu?

Check the wrapped error: it names the exact file and whether it was a read or parse failure

discovering ambient OCI registry credentials: %w

Error message

discovering ambient OCI registry credentials: %w

What it means

OpenTofu assembles its OCI credentials configuration in the oci_default_credentials CLI-config block; this error means the 'ambient discovery' step (reading Docker-style config files and credential helpers from standard locations) failed while building that configuration. In practice it is only reachable when discover_ambient_credentials = true is combined with an explicit docker_style_config_files list, because with automatic discovery the CLI deliberately ignores per-file anomalies. The underlying cause is reported by the wrapped error.

Source

Thrown at internal/command/cliconfig/oci_credentials.go:74

		}
		defaultCredentialsBlock = c.OCIDefaultCredentials[0]
	} else {
		defaultCredentialsBlock = newDefaultOCIDefaultCredentials()
	}

	discoverAmbientCredentials := defaultCredentialsBlock.DiscoverAmbientCredentials
	dockerStyleConfigFiles := defaultCredentialsBlock.DockerStyleConfigFiles
	if defaultCredentialsBlock.DefaultDockerCredentialHelper != "" {
		cfgs = append(cfgs, ociauthconfig.NewGlobalDockerCredentialHelperCredentialsConfig(
			"oci_default_credentials block",
			defaultCredentialsBlock.DefaultDockerCredentialHelper,
		))
	}

	if discoverAmbientCredentials {
		ambientCfgs, err := discoverAmbientOCICredentials(ctx, dockerStyleConfigFiles, discoEnv)
		if err != nil {
			return ociauthconfig.CredentialsConfigs{}, fmt.Errorf("discovering ambient OCI registry credentials: %w", err)
		}
		cfgs = append(cfgs, ambientCfgs...)
	}
	return ociauthconfig.NewCredentialsConfigs(cfgs), nil
}

func discoverAmbientOCICredentials(ctx context.Context, dockerStyleConfigFiles []string, discoEnv ociauthconfig.ConfigDiscoveryEnvironment) ([]ociauthconfig.CredentialsConfig, error) {
	if dockerStyleConfigFiles != nil {
		// explicit config file locations
		// (non-nil but empty represents completely disabling our search for
		// Docker-style configuration files.)
		cfgs, err := ociauthconfig.FixedDockerCLIStyleCredentialsConfigs(
			ctx,
			dockerStyleConfigFiles,
			discoEnv,
		)
		if err != nil {
			// If the user explicitly configured search paths then we treat a failure to

View on GitHub (pinned to 3561785c48)

Solutions

Check the wrapped error: it names the exact file and whether it was a read or parse failure
Verify every path in docker_style_config_files exists, is readable, and contains valid JSON (e.g. jq . <file>)
Fix permissions (chmod 644) or correct the path spelling
If the files were not intentional, remove docker_style_config_files to return to automatic discovery, which tolerates missing/broken files
Set docker_style_config_files = [] if you want ambient Docker-style lookup fully disabled

Example fix

# before (CLI config)
oci_default_credentials {
  discover_ambient_credentials = true
  docker_style_config_files = ["/home/me/.docker/config.jsom"]
}
# after
ci_default_credentials {}  # typo removed; automatic discovery of default locations

Defensive patterns

Strategy: validation

Validate before calling

// Before enabling discovery with explicit files, verify each is readable JSON.
func validateDockerStyleFiles(paths []string) error {
	for _, p := range paths {
		fi, err := os.Stat(p)
		if err != nil {
			return fmt.Errorf("%s: %w", p, err)
		}
		if fi.IsDir() || fi.Mode().Perm()&0o400 == 0 {
			return fmt.Errorf("%s: not readable", p)
		}
		data, err := os.ReadFile(p)
		if err != nil {
			return fmt.Errorf("%s: %w", p, err)
		}
		if !json.Valid(data) {
			return fmt.Errorf("%s: not valid JSON", p)
		}
	}
	return nil
}

Prevention

Run a config lint (json checks) on docker_style_config_files in CI before invoking OpenTofu
Prefer omitting docker_style_config_files unless you truly need custom locations; automatic discovery tolerates broken files
Keep Docker config files owned by the same user that runs OpenTofu

When it happens

Trigger: An oci_default_credentials block with discover_ambient_credentials = true and a docker_style_config_files list where at least one listed file is unreadable (permissions, path type) or is not valid JSON; discoverAmbientOCICredentials -> FixedDockerCLIStyleCredentialsConfigs returns an error which is wrapped here.

Common situations: Typo in a docker_style_config_files path; pointing at a file with restrictive permissions; a partially-written or hand-edited Docker config.json; CI images where $HOME/.docker does not exist at the explicitly-given path.

Related errors

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