🚨 OpenTofu Error: 'Reference to undeclared resource' — Cause, Fix, and Troubleshooting Guide

Overview

When you write aws_instance.web.id, OpenTofu expects a resource "aws_instance" "web" block to exist in the same module. If it cannot find one — because of a typo, a deleted block, or a reference across a module boundary — it fails during validation:

Error: Reference to undeclared resource

  on main.tf line 42, in resource "aws_eip" "web":
  42:   instance = aws_instance.webserver.id

A managed resource "aws_instance" "webserver" has not been declared in the
root module.

Symptoms

• tofu validate or tofu plan fails with Reference to undeclared resource.
• The message points at the exact line and names the resource address it could not resolve.
• It often appears after renaming a resource, deleting one, or splitting configuration into modules.
• The suffix names the scope: “in the root module” or “in module.”.

Common Root Causes

• Typo in the resource name — aws_instance.webserver vs the declared aws_instance.web.
• Resource deleted or renamed but references to it remain elsewhere.
• Wrong module scope — you referenced a child module’s resource directly instead of via an output.
• Wrong resource type — aws_instance.web referenced as aws_ec2_instance.web.
• Copy-paste from another module where the resource actually lived.

How to diagnose

Let OpenTofu point you at the line, then confirm what is actually declared:

tofu validate
grep -rn 'resource "aws_instance"' *.tf

List every resource address OpenTofu currently knows about:

tofu plan 2>&1 | sed -n '1,20p'
grep -rn 'aws_instance\.' *.tf

If the resource lives in a child module, you cannot reference it directly — check for an output:

grep -rn 'output ' modules/network/

Fixes

Fix the typo so the reference matches the declared name exactly:

# declared: resource "aws_instance" "web" { ... }
resource "aws_eip" "web" {
  instance = aws_instance.web.id   # was aws_instance.webserver.id
}

Expose child-module resources through outputs and reference the output, not the resource:

# modules/network/outputs.tf
output "instance_id" {
  value = aws_instance.web.id
}

# root
resource "aws_eip" "web" {
  instance = module.network.instance_id
}

Re-add or restore a resource block that was deleted while references remain, or remove the dangling references.

Validate the whole tree after edits:

tofu validate

What to watch out for

• Resource addresses are scoped to a single module; crossing a module boundary always goes through outputs and variables.
• Renaming a resource changes its address — update every reference and consider a moved block to preserve state.
• tofu validate catches these before any API calls; run it in CI and pre-commit.
• Editor “find and replace” across files is the fastest safe way to rename a resource and its references together.

Related

• OpenTofu Error: ‘Unsupported argument’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Missing required argument’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Cycle’ — Cause, Fix, and Troubleshooting Guide