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

Emitted by `Config.Validate` (cliconfig.go:314-317) when more than one `credentials_helper` block is present across the merged CLI config. Terraform allows zero or one such blocks; the HCL decode produces a map keyed by helper type, so two different helper types push the map length above one.

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 c9def3e214)

Solutions

Keep exactly one `credentials_helper` block across all CLI config files.
Search all loaded files (main `.terraformrc` plus every `*.tfrc`/`*.tfrc.json` in the config dir) for duplicate blocks.
Remove or comment out the helper you no longer want.
Re-run `terraform init`; `Validate` re-checks on every load.

Example fix

# before
credentials_helper "atlas" { args = [] }
credentials_helper "vault" { args = ["-path=secret"] }
# No more than one credentials_helper block may be specified

# after
credentials_helper "vault" { args = ["-path=secret"] }

Defensive patterns

Strategy: validation

Validate before calling

// Count credentials_helper blocks across all loaded CLI config files.
func countCredentialsHelpers(files []string) (int, error) {
    n := 0
    for _, f := range files {
        b, err := os.ReadFile(f)
        if err != nil {
            continue
        }
        if bytes.Contains(b, []byte("credentials_helper")) {
            n++
        }
    }
    return n, nil
}
// if n > 1 -> reject before running terraform.

Prevention

Keep at most one `credentials_helper` block in all CLI config files combined.
Audit team-shared `*.tfrc` files before merging into personal config.
Remember Merge concatenates files, so duplicates add up across files.

When it happens

Trigger: Defining two `credentials_helper "<type>" { }` blocks (with different type labels) in the same `.terraformrc`, or one in `.terraformrc` plus another in a `~/.terraform.d/*.tfrc` file that gets merged.

Common situations: Adding a new helper (e.g. `atlas`/`vault`) without removing the previous one; merging personal config with a team-supplied `*.tfrc` that also declares a helper.

Related errors

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