hashicorp/terraform · error

root module not found. Please run terraform init

Error message

root module not found. Please run terraform init

What it means

Returned by the `terraform modules` command when `loadSingleModule(rootModPath)` returns a nil root module. The most common cause is that the working directory's module tree has not been installed/initialized, so the root module artifact that Terraform expects is absent.

Solutions

1. Run `terraform init` in the working directory to install modules, then re-run `terraform modules`.
2. If init fails, resolve the module source errors in the `module` blocks and re-init.
3. Run the command from the directory that actually contains the root module (check `-chdir` / working dir).

Example fix

# before
terraform modules   # in a fresh dir -> error
# after
terraform init && terraform modules

// Equivalent precondition: ensure the module tree is installed before listing.
if _, err := c.loadSingleModule(rootModPath); err != nil || rootModEarly == nil {
    return errors.New("run `terraform init` first")
}

When it happens

Trigger: Running `terraform modules` (or a command that calls `loadSingleModule`) in a directory where `.terraform/modules/` and the installed module tree are missing — i.e. `terraform init` was never run, or ran with `-lock=false`/network errors that left modules uninstalled.

Common situations: Fresh clone where someone runs `terraform modules` before `terraform init`; CI job that skips init; module installation failed partway and left an incomplete `.terraform`.

Related errors

• cannot read
• failed to create directory
• failed to initialize cloudplugin cache directory
• failed to read module manifest
• unknown view type

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

Appendix: source

Thrown at internal/command/modules.go:78

		loader.Parser().ForceFileSource(filename, src)
	})
	diags = diags.Append(varDiags)
	if diags.HasErrors() {
		view.Diagnostics(diags)
		return 1
	}

	rootModPath, err := ModulePath([]string{})
	if err != nil {
		diags = diags.Append(err)
		view.Diagnostics(diags)
		return 1
	}

	// Read the root module path so we can then traverse the tree
	rootModEarly, earlyConfDiags := c.loadSingleModule(rootModPath)
	if rootModEarly == nil {
		diags = diags.Append(errors.New("root module not found. Please run terraform init"), earlyConfDiags)
		view.Diagnostics(diags)
		return 1
	}

	diags = diags.Append(c.resolveConstVariables(rootModPath, args.ViewType))
	if diags.HasErrors() {
		view.Diagnostics(diags)
		return 1
	}

	config, confDiags := c.loadConfig(rootModPath)
	// Here we check if there are any uninstalled dependencies
	versionDiags := terraform.CheckCoreVersionRequirements(config)
	if versionDiags.HasErrors() {
		view.Diagnostics(versionDiags)
		return 1
	}

View on GitHub (pinned to d32a084675)