hashicorp/terraform · error

Terraform encountered problems during initialisation, includ

Error message

Terraform encountered problems during initialisation, including problems
with the configuration, described below.

The Terraform configuration must be valid before initialization so that
Terraform can determine which modules and providers need to be installed.

What it means

errInitConfigError (init_run.go:125) is a preamble diagnostic appended when the root module fails to load at all during early config parsing (rootModEarly == nil). It frames the underlying parsing diagnostics, telling the developer Terraform cannot determine modules/providers to install until the configuration is syntactically and semantically valid. The actual parse errors follow in earlyConfDiags.

Source

Thrown at internal/command/init_run.go:125

	if err != nil {
		diags = diags.Append(fmt.Errorf("Error checking configuration: %s", err))
		view.Diagnostics(diags)
		return 1
	}
	if empty {
		view.Output(views.OutputInitEmptyMessage)
		return 0
	}

	// Load just the root module to begin backend and module initialization
	rootModEarly, earlyConfDiags := c.loadSingleModuleWithTests(path, initArgs.TestsDirectory)

	// There may be parsing errors in config loading but these will be shown later _after_
	// checking for core version requirement errors. Not meeting the version requirement should
	// be the first error displayed if that is an issue, but other operations are required
	// before being able to check core version requirements.
	if rootModEarly == nil {
		diags = diags.Append(errors.New(errInitConfigError), earlyConfDiags)
		view.Diagnostics(diags)

		return 1
	}
	if !(c.Meta.AllowExperimentalFeatures && initArgs.EnablePssExperiment) && rootModEarly.StateStore != nil {
		// TODO(SarahFrench/radeksimko) - remove when this feature isn't experimental.
		// This approach for making the feature experimental is required
		// to let us assert the feature is gated behind an experiment in tests.
		// See https://github.com/hashicorp/terraform/pull/37350#issuecomment-3168555619

		detail := "Pluggable state store is an experiment which requires"
		if !c.Meta.AllowExperimentalFeatures {
			detail += " an experimental build of terraform"
		}
		if !initArgs.EnablePssExperiment {
			if !c.Meta.AllowExperimentalFeatures {
				detail += " and"
			}

View on GitHub (pinned to c9def3e214)

Solutions

1. Run 'terraform validate' or 'terraform fmt' to surface the underlying parse error in earlyConfDiags.
2. Fix the syntax/type error reported in the appended diagnostics, then re-run 'terraform init'.
3. Check file permissions and that .tf files are readable by the current user.
4. Ensure required_providers and terraform block syntax are correct (no malformed blocks).

Example fix

// before: main.tf has a syntax error -> rootModEarly nil
// resource "aws_instance" "web" {
//   ami = "ami-x"
//   // missing closing brace
//
// after
// resource "aws_instance" "web" {
//   ami = "ami-x"
// }

// Pre-validate the root module with 'terraform validate' style parsing before init.
func preflightRootModule(dir string) error {
    parser := configs.NewParser(nil)
    _, diags := parser.LoadConfigDir(dir)
    if diags.HasErrors() {
        return fmt.Errorf("root module parse error: %w", diags.Err())
    }
    return nil
}

When it happens

Trigger: Line 117-129: loadSingleModuleWithTests returns a nil rootModEarly (catastrophic parse failure, e.g. unreadable/corrupt main .tf file); errors.New(errInitConfigError) is appended together with earlyConfDiags and run returns 1 before the version-requirement check.

Common situations: A syntax error in main.tf so severe the module cannot load; a missing/typo'd required_providers block preventing module load; file permission errors reading .tf files; HCL that breaks the parser entirely.

Related errors

• The working directory already contains files. The -from-modu
• The -upgrade flag conflicts with -lockfile=readonly.
• empty state name
• Attempted to initialize pluggable state with an empty string
• missing state name

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