hashicorp/terraform · error

failed to read module manifest: %s

Error message

failed to read module manifest: %s

What it means

Raised by NewLoader when modules.readModuleManifestSnapshot() fails to read or parse the module manifest (.terraform/modules/modules.json). The manifest records which modules are installed and where; if it is missing, unreadable, or contains invalid JSON, the loader cannot build the module install graph. Hit at the very start of any command that needs a Loader (line 90-92).

Source

Thrown at internal/configs/configload/loader.go:92

	parser := configs.NewParser(fs)
	reg := registry.NewClient(config.Services, nil)

	ret := &Loader{
		parser: parser,
		modules: moduleMgr{
			FS:         afero.Afero{Fs: fs},
			CanInstall: true,
			Dir:        config.ModulesDir,
			Services:   config.Services,
			Registry:   reg,
		},
		parserOpts: make([]configs.Option, 0),
	}

	err := ret.modules.readModuleManifestSnapshot()
	if err != nil {
		return nil, fmt.Errorf("failed to read module manifest: %s", err)
	}

	if config.IncludeQueryFiles {
		ret.parserOpts = append(ret.parserOpts, configs.MatchQueryFiles())
	}

	if config.IncludeStateMigrateFiles {
		ret.parserOpts = append(ret.parserOpts, configs.MatchStateMigrateFiles())
	}

	return ret, nil
}

// ModulesDir returns the path to the directory where the loader will look for
// the local cache of remote module packages.
func (l *Loader) ModulesDir() string {
	return l.modules.Dir
}

View on GitHub (pinned to c9def3e214)

Solutions

1. Wipe the local module cache and reinit: `rm -rf .terraform && terraform init`.
2. If only the manifest is bad, delete `.terraform/modules/modules.json` and run `terraform get -update` then `terraform init`.
3. Check filesystem permissions on the .terraform directory.

Example fix

// before: NewLoader returns "failed to read module manifest: ..."

$ rm -rf .terraform && terraform init

// Treat .terraform/ as disposable. In CI, never cache .terraform/modules across
// jobs; run `terraform init` from a clean checkout to guarantee a valid manifest.
// If you must cache, verify modules.json parses as JSON before reuse.

When it happens

Trigger: A corrupted or half-written modules.json (interrupted `terraform get`/`init`), a manually edited manifest with invalid JSON, permission errors reading .terraform/modules/, or an empty/garbage file from a failed download.

Common situations: Interrupted init, disk-full during module download, syncing .terraform across machines/OSes, git operations that touched .terraform/modules, stale manifest after switching branches.

Related errors

• root module not found. Please run terraform init
• failed to create local modules directory: %s
• Module installation was canceled by an interrupt signal.
• failed to determine the configuration's provider requirement
• provider %s: required by this configuration but no version i

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