No more than one credentials_helper block may be specified

Error message

No more than one credentials_helper block may be specified

What it means

Thrown when the CLI configuration contains more than one credentials_helper block. Terraform allows at most one credentials_helper to avoid ambiguity about which plugin handles credential storage and retrieval. The check runs during config validation after all config files are parsed and merged.

Solutions

Remove all but one credentials_helper block from your .terraformrc
If using config file merging, ensure only one file defines credentials_helper
Review the full config including any file pointed to by TF_CLI_CONFIG_FILE

Example fix

// before
dev_overrides {}
credentials_helper "foo" { args = [] }
credentials_helper "bar" { args = [] }

// after
credentials_helper "foo" { args = [] }

Defensive patterns

Strategy: validation

Validate before calling

// Count credentials_helper blocks in config before deployment
func countCredentialsHelpers(path string) (int, error) {
    src, err := os.ReadFile(path)
    if err != nil {
        return 0, err
    }
    return strings.Count(string(src), "credentials_helper"), nil
}

Prevention

Define at most one credentials_helper block across all config files
Audit merged config files for duplicate blocks
Use a single source of truth for CLI configuration
Run a config lint step in CI that checks for duplicate top-level blocks

When it happens

Trigger: len(c.CredentialsHelpers) > 1 after parsing and merging all config file(s). This happens when multiple credentials_helper blocks appear in the same file or across merged config files (e.g., user config plus TF_CLI_CONFIG_FILE).

Common situations: Copy-pasting a credentials_helper block creating duplicates; merging multiple config files each defining their own credentials_helper; config file from a different setup pasted without removing the existing block.

Related errors

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/86c0e4560c0bfee5. Report an issue: GitHub.

Appendix: source

Thrown at internal/command/cliconfig/cliconfig.go:316

				fmt.Errorf("The host %q block has an invalid hostname: %s", givenHost, err),
			)
		}
	}

	// Check that all "credentials" blocks have valid hostnames.
	for givenHost := range c.Credentials {
		_, err := svchost.ForComparison(givenHost)
		if err != nil {
			diags = diags.Append(
				fmt.Errorf("The credentials %q block has an invalid hostname: %s", givenHost, err),
			)
		}
	}

	// Should have zero or one "credentials_helper" blocks
	if len(c.CredentialsHelpers) > 1 {
		diags = diags.Append(
			fmt.Errorf("No more than one credentials_helper block may be specified"),
		)
	}

	// Should have zero or one "provider_installation" blocks
	if len(c.ProviderInstallation) > 1 {
		diags = diags.Append(
			fmt.Errorf("No more than one provider_installation block may be specified"),
		)
	}

	if c.PluginCacheDir != "" {
		_, err := os.Stat(c.PluginCacheDir)
		if err != nil {
			diags = diags.Append(
				fmt.Errorf("The specified plugin cache dir %s cannot be opened: %s", c.PluginCacheDir, err),
			)
		}
	}

View on GitHub (pinned to d32a084675)