How to fix Error: Reference to undeclared module in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 132 views

This error occurs when Terraform tries to reference a module that hasn't been declared in the current configuration scope. Learn how to properly declare modules and pass values between them.

Quick fix

Fixes Error: Reference to undeclared module

module "networking" {
  source = "./modules/networking"
  # ... other configuration
}
  1. Verify the module is declared in your configuration
  2. Check for module name typos
  3. For cross-module references, use module outputs
  4. Run terraform init to initialize modules
terraform — error
module "networking" {
  source = "./modules/networking"
  # ... other configuration
}
Error: Reference to undeclared module

What this error means

Terraform modules have their own scope. When you try to reference a module like `module.networking.vpc_id` without declaring that module in your current configuration, Terraform cannot find it. This typically happens when: 1. A module block hasn't been declared in the calling configuration 2. A module in one scope tries to reference a sibling module directly 3. The module name doesn't match the declaration exactly (case-sensitive) 4. Module files haven't been initialized yet Unlike global variables, Terraform modules must be explicitly declared and their outputs explicitly referenced through the module.LABEL.OUTPUT syntax.

Typical symptoms

  • Terraform plan/apply fails with 'Error: Reference to undeclared module'
  • Error message shows the exact module name that couldn't be found
  • Configuration references a module like `module.networking` that was never declared
  • Cross-module references fail even though the module exists elsewhere

Common causes

  1. Module block is not declared in the root or current module configuration
  2. Child module tries to reference a sibling module directly without parent passing the value
  3. Typo in module name in the reference (e.g., `module.netwrok` instead of `module.networking`)
  4. Module not initialized after adding new module declarations
  5. Referring to a module from inside another module without proper variable passing

How to fix "Error: Reference to undeclared module"

1Verify the module is declared in your configuration

Check that you have a module block declaring the module you're trying to reference. For example, if referencing module.networking, you must have declared it:

hcl
module "networking" {
  source = "./modules/networking"
  # ... other configuration
}

Ensure the label (name after module) matches exactly what you're referencing elsewhere.

2Check for module name typos

Module names are case-sensitive in Terraform. If your declaration uses module "Networking" but you reference module.networking, it won't work.

Double-check:
- Spelling of the module name
- Capitalization
- Special characters

The label between module "" and the reference must match exactly.

3For cross-module references, use module outputs

If you have a child module that needs to reference another module's output, you must pass it through the parent (root) module:

In root main.tf:

hcl
module "networking" {
  source = "./modules/networking"
}

module "security" {
  source          = "./modules/security"
  vpc_id          = module.networking.vpc_id  # Pass output as input
}

In modules/security/variables.tf:

hcl
variable "vpc_id" {
  description = "VPC ID from networking module"
  type        = string
}

This way, the security module receives the value as a variable instead of trying to reference the networking module directly.

4Run terraform init to initialize modules

After declaring new modules, initialize them:

bash
terraform init

This downloads and prepares all declared modules. If you've recently added module blocks but haven't run init, the modules won't be available.

5Validate your configuration

Use terraform validate to check for syntax errors and scope issues:

bash
terraform validate

This will catch many undeclared module references before you attempt a plan or apply.

6For monolithic modules, ensure proper scope

If you're working with a single root configuration file that references multiple modules, all module blocks must be in the same file or included via Terraform's configuration merging (same directory).

Example structure:

bash
.
├── main.tf           # Contains module blocks
├── variables.tf      # Input variables
├── outputs.tf        # Outputs
└── modules/
    ├── networking/
    └── security/

All module "..." blocks must be in the root configuration files (main.tf, modules.tf, etc.) at the same level.

Advanced notes

Module scope in Terraform is hierarchical. The root module is the entry point, and each child module has its own scope. You cannot directly reference sibling modules from within a child module—only parent-declared modules. If you need values from multiple sources in a child module, they must all be passed as input variables from the parent. For complex scenarios, consider using for_each loops with modules or conditional module creation using count/for_each to manage interdependencies more cleanly.

Frequently asked questions

What does "Error: Reference to undeclared module" mean?
Terraform modules have their own scope. vpc_id without declaring that module in your current configuration, Terraform cannot find it. This typically happens when: 1.
How do I fix "Error: Reference to undeclared module"?
This error occurs when Terraform tries to reference a module that hasn't been declared in the current configuration scope. Learn how to properly declare modules and pass values between them.
What causes "Error: Reference to undeclared module"?
Module block is not declared in the root or current module configuration Child module tries to reference a sibling module directly without parent passing the value Typo in module name in the reference (e.g., module.netwrok instead of module.networking)
Is the "Error: Reference to undeclared module" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading