TerraformPilot

DevOps

Fix Terraform Error: Module Not Installed

Fix terraform module not installed errors. Run terraform init, fix module source paths, handle Git refs

LLuca Berton1 min read

Quick Answer

# 
terraform init

That's it in 90% of cases. Terraform needs to download/link modules before plan or apply.

The Error

# 
Error: Module not installed
 
  on main.tf line 10:
  10: module "vpc" {
 
This module is not yet installed. Run "terraform init" to install all modules
required by this configuration.

What Causes This

#
  1. Never ran terraform init — fresh clone, new module added
  2. .terraform/ deleted — cleaned up cache, CI/CD fresh workspace
  3. Module source changed — updated source URL but didn't re-init
  4. Git submodule not cloned — source points to unresolved path
  5. Private registry auth missing — can't download from private registry

Solution 1: Run terraform init

# 
terraform init

This downloads all modules to .terraform/modules/.

If source changed, you may need:

terraform init -upgrade

Solution 2: Clean and Reinitialize

# 
rm -rf .terraform .terraform.lock.hcl
terraform init

Solution 3: Fix Module Source Paths

#

Common source format mistakes:

# Local module — relative path from current directory
module "vpc" {
  source = "./modules/vpc"       # ✅ Correct
  source = "modules/vpc"         # ❌ Missing ./
  source = "../shared/modules/vpc"  # ✅ Relative path up
}
 
# Registry module — org/name/provider format
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"  # ✅
  version = "~> 5.0"
}
 
# Git module — double slash separates repo from subdirectory
module "vpc" {
  source = "git::https://github.com/org/infra.git//modules/vpc?ref=v1.0"  # ✅
  source = "git::https://github.com/org/infra.git/modules/vpc?ref=v1.0"   # ❌ Single slash
}
 
# GitHub shorthand
module "vpc" {
  source = "github.com/org/terraform-modules//vpc?ref=v2.0"  # ✅
}

Solution 4: Git Authentication for Private Modules

# 
# SSH key (most common)
module "vpc" {
  source = "git::ssh://git@gitlab.com/myorg/modules.git//vpc?ref=v1.0"
}
 
# Ensure SSH key is loaded
ssh-add ~/.ssh/id_rsa
ssh -T git@gitlab.com   # Test connectivity
 
# HTTPS with token
module "vpc" {
  source = "git::https://oauth2:${GITLAB_TOKEN}@gitlab.com/myorg/modules.git//vpc?ref=v1.0"
}

In CI/CD, configure Git credentials:

# GitLab CI
before_script:
  - git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/".insteadOf "https://gitlab.com/"
  - terraform init

Solution 5: Private Registry Authentication

# 
# ~/.terraformrc
credentials "app.terraform.io" {
  token = "your-team-token"
}
 
credentials "gitlab.com" {
  token = "your-gitlab-token"
}

Debugging

# 
# See what modules are installed
ls -la .terraform/modules/
 
# Verbose init output
TF_LOG=DEBUG terraform init 2>&1 | grep -i module
 
# Verify module directory structure
find .terraform/modules/ -name "*.tf" | head -20

CI/CD: Cache Modules

#

Speed up pipelines by caching modules:

# GitLab CI
cache:
  key: terraform-modules-${CI_COMMIT_REF_SLUG}
  paths:
    - .terraform/modules/
    - .terraform/providers/

Hands-On Courses

#

Conclusion

#

Module not installed = run terraform init. If that doesn't work, check the source path format (local needs ./, Git needs // double-slash for subdirectories), verify Git SSH/HTTPS authentication for private repos, and use terraform init -upgrade when source URLs change.

#Terraform#Troubleshooting#DevOps#Error Fix#Infrastructure as Code

Share this article

Related articles