⚙️ OpenTofu Error: 'Reference to undeclared input variable' Missing variable Block

Exact Error Message

╷
│ Error: Reference to undeclared input variable
│
│   on main.tf line 8, in resource "aws_instance" "web":
│    8:   instance_type = var.instance_type
│
│ An input variable with the name "instance_type" has not been declared. This
│ variable can be declared with a variable "instance_type" {} block.
╵

The message names the exact variable reference that has no matching declaration and suggests the variable "<name>" {} block you need to add.

What It Means

Every value you reference as var.something must have a corresponding variable "something" {} declaration in the same module. Unlike some languages, OpenTofu does not auto-create variables from .tfvars files or -var flags. A .tfvars entry only supplies a value for a variable that is already declared; it never declares one.

When OpenTofu parses your configuration and finds a var. reference with no matching variable block in that module, it stops with Reference to undeclared input variable. This is almost always a missing declaration, a typo in the name, or a variable declared in a different module than the one that uses it.

Common Causes

• The variable block was never written, but the configuration already references var.name.
• A typo: the declaration says instance_size but the reference says var.instance_type.
• The variable is declared in the root module but referenced inside a child module (or vice versa) — declarations are per-module and do not cross the boundary.
• A variable block was deleted during a refactor while its references remained.
• A value exists in terraform.tfvars and the author assumed that was enough to declare it.

Diagnostic Commands

Let OpenTofu point at the exact undeclared reference:

tofu validate

Find every place the variable is referenced:

grep -rn 'var.instance_type' .

Confirm whether a matching declaration exists anywhere in this module:

grep -rn 'variable "instance_type"' .

List the variables OpenTofu actually recognizes for the current module:

tofu console
> var

Step-by-Step Resolution

1. Run tofu validate and read the file and line it reports. The reference (for example var.instance_type) is what needs a declaration.

2. Check whether a variable block with that exact name exists in the same module directory:

grep -rn 'variable "instance_type"' .

3. If it is missing, add the declaration. Put it in variables.tf in the module that uses it:

variable "instance_type" {
  type        = string
  description = "EC2 instance type for the web tier."
  default     = "t3.micro"
}

4. If the declaration exists but the names differ, fix the typo so the reference and declaration match exactly:

# reference and declaration must agree
instance_type = var.instance_type

5. If the variable belongs to a child module, declare it inside that child module and pass it in from the parent as a module argument:

module "web" {
  source        = "./modules/web"
  instance_type = var.instance_type
}

6. Re-validate and plan to confirm the reference now resolves:

tofu validate && tofu plan

Prevention

• Declare every variable in a variables.tf file per module so declarations are easy to find and audit.
• Remember that .tfvars files and -var flags supply values but never declare variables; the variable block is mandatory.
• Keep declarations and references in the same module; passing data across a module boundary requires an explicit argument in the module block plus a declaration in the child.
• Run tofu validate in CI so a missing declaration fails fast, before apply.
• When refactoring, remove references and declarations together. The prompt library includes prompts that scaffold matching variable blocks for a set of references.

Related Errors

• No value for required variable — the variable is declared but no value was supplied.
• Reference to undeclared module — the same class of error for a module. reference instead of var..
• Reference to undeclared resource — a resource-type reference with no matching resource block.
• Invalid value for variable — the variable is declared and a value was passed, but a validation rule rejected it.

Frequently Asked Questions

Doesn’t putting the value in terraform.tfvars declare the variable? No. A .tfvars file only assigns values. You must still write a variable "name" {} block, or OpenTofu treats the reference as undeclared.

Why does it work in the root module but fail in a child module? Variable declarations are scoped to a single module. A child module cannot see the root’s variables; it needs its own variable block and an argument passed in from the parent.

Can I declare a variable without a type or default? Yes. A bare variable "name" {} is valid and defaults to an optional any-typed variable, but adding type and description makes the module far clearer.

How do I find all undeclared references at once? Run tofu validate, which reports each undeclared reference, and cross-check with grep -rn 'var\.' against your variable declarations.

Where can I see more OpenTofu fixes? Browse the OpenTofu guides for the complete set of error walkthroughs.