🚨 OpenTofu Error: 'Module not installed' — Cause, Fix, and Troubleshooting Guide

Overview

OpenTofu downloads and records every module block’s source under .terraform/modules/ during tofu init. If you run plan/apply before init, or in a fresh checkout where .terraform/ is absent, OpenTofu cannot find the module code and stops:

Error: Module not installed

  on main.tf line 12:
  12: module "vpc" {

This module is not yet installed. Run "tofu init" to install all modules
required by this configuration.

Symptoms

• tofu plan/apply fails with Module not installed and points at a module block.
• Always appears in a clean clone or a CI runner that skipped init.
• Also appears after adding a new module block without re-running init.
• May accompany “Module source has changed” if you edited a source.

Common Root Causes

• tofu init never ran in this working directory / runner.
• New module added to config but init not re-run to fetch it.
• .terraform/ not persisted between CI stages (plan stage vs apply stage).
• source changed (registry version, git ref, path) requiring re-install.
• Corrupted .terraform/modules/ from an interrupted download.

How to diagnose

Check whether the module cache exists and what it contains:

ls -la .terraform/modules/
cat .terraform/modules/modules.json | jq '.Modules[].Key'

Reproduce with a clean init to see what gets installed:

tofu init

Confirm the module source addresses you declared:

grep -nA4 'module "' *.tf

Fixes

Just initialize — this downloads all modules and providers:

tofu init
tofu plan

After adding or changing a module, re-init (use -upgrade to pull newer registry/git refs):

tofu init -upgrade

In CI, always init before plan/apply and, if you split stages, either re-init in each or persist .terraform/:

tofu init -input=false
tofu plan -input=false -out=tfplan
# later stage (same runner/artifact):
tofu apply -input=false tfplan

Recover a corrupt cache by removing it and re-installing (safe — it is local only):

rm -rf .terraform/modules
tofu init

What to watch out for

• .terraform/ is machine-specific — never commit it; run tofu init in every environment instead.
• If you split plan and apply into separate CI jobs, carry the .terraform/ directory and the saved plan as artifacts, or re-init in the apply job.
• Changing a module source or version requires init again; init -upgrade for newer refs.
• Use -input=false in automation so a prompt never silently hangs the pipeline.

Related

• OpenTofu Error: ‘Failed to query available provider packages’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Backend configuration changed’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Inconsistent dependency lock file’ — Cause, Fix, and Troubleshooting Guide