What causes "Failed to initialize config loader: %w" in hashicorp/terraform?

Inspect the wrapped error message for the specific cause (filesystem path, permission, or parse error).

Failed to initialize config loader: %w

Error message

Failed to initialize config loader: %w

What it means

Wrapped error from ModulesCommand.internalManifest when Meta.initConfigLoader() (configload.NewLoader) fails. The config loader is responsible for parsing .terraformrc/CLI config and setting up the module installer; failure here means Terraform cannot even begin to enumerate modules. The %w preserves the underlying cause (e.g. bad modules directory, services init failure).

Source

Thrown at internal/command/modules.go:133

	// Create a module reference resolver
	resolver := moduleref.NewResolver(internalManifest)

	// Crawl the Terraform config and find entries with references
	manifestWithRef := resolver.Resolve(config)

	// Render the new manifest with references
	return view.Display(*manifestWithRef)
}

// internalManifest will use the configuration loader to refresh and load the
// internal manifest.
func (c *ModulesCommand) internalManifest() (modsdir.Manifest, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics

	loader, err := c.initConfigLoader()
	if err != nil {
		diags = diags.Append(fmt.Errorf("Failed to initialize config loader: %w", err))
		return nil, diags
	}

	if err = loader.RefreshModules(); err != nil {
		diags = diags.Append(fmt.Errorf("Failed to refresh module manifest: %w", err))
		return nil, diags
	}

	return loader.ModuleManifest(), diags
}

const modulesCommandHelp = `
Usage: terraform [global options] modules [options]

  Prints out a list of all declared Terraform modules and their resolved versions
  in a Terraform working directory.

Options:

View on GitHub (pinned to c9def3e214)

Solutions

Inspect the wrapped error message for the specific cause (filesystem path, permission, or parse error).
Validate TF_CLI_CONFIG_FILE / ~/.terraformrc is valid HCL and readable.
Check the data directory (TF_DATA_DIR) exists and is writable; clear .terraform/modules if corrupted.
Run 'terraform modules' with TF_LOG=trace to surface the underlying NewLoader error.

Example fix

// before: TF_CLI_CONFIG_FILE=/etc/tf/bad-config.tfrc  (malformed)
// after: provide a valid CLI config or unset the var
$ unset TF_CLI_CONFIG_FILE
$ terraform modules

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight: ensure CLI config and data dir are usable before invoking 'terraform modules'
package main

func preflightConfigLoader(cliConfig, dataDir string) error {
	if cliConfig != "" {
		if _, err := os.ReadFile(cliConfig); err != nil {
			return fmt.Errorf("TF_CLI_CONFIG_FILE unreadable: %w", err)
		}
	}
	if info, err := os.Stat(dataDir); err == nil && !info.IsDir() {
		return fmt.Errorf("data dir %s is not a directory", dataDir)
	}
	return nil
}

Prevention

Run 'terraform init' once before 'terraform modules' in fresh checkouts.
Keep TF_CLI_CONFIG_FILE pointing at version-controlled, valid HCL.
Make the data directory writable in CI runners.

When it happens

Trigger: Running 'terraform modules' (or 'terraform modules -json') when configload.NewLoader returns an error — typically an inaccessible modules directory, a corrupt CLI config file, or a services/registry client initialization failure.

Common situations: TF_CLI_CONFIG_FILE points at a malformed or unreadable file; the modules dir (TF_DATA_DIR/.terraform/modules) has permission errors; running in a restricted filesystem/container where the loader cannot stat or create its working files.

Related errors

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