🚨 Terraform Error Guide: 'Duplicate variable declaration' — Remove the Redeclared Variable Block

Overview

Duplicate variable declaration is a configuration-loading error. Within a single Terraform module, every input variable name must be unique. Terraform reads all .tf files in the working directory and merges them into one namespace; if two variable "<name>" blocks share the same name — whether in the same file or, more often, split across variables.tf and another file — Terraform cannot decide which definition wins and aborts during init, validate, or plan.

The literal message points at the second declaration and back at the first:

Error: Duplicate variable declaration

  on network.tf line 3:
   3: variable "region" {

A variable named "region" was already declared at variables.tf:1,1-19.
Variable names must be unique within a module.

The message always names both locations: the file and line of the duplicate you are looking at, and the already declared at <file>:<line> for the original. That second path is the other half of the pair you need to reconcile.

This error is about declaring the same variable twice (two variable blocks), which is not allowed. It is different from assigning a value twice (in .tfvars, -var, or environment variables), which Terraform resolves by precedence rather than by erroring.

Symptoms

• terraform init, terraform validate, or terraform plan fails immediately with Duplicate variable declaration.
• The message names two files/lines: the current duplicate and the already declared at ... original.
• It often appears after a merge, a refactor that split or moved variable blocks, or copy-pasting a variable block into the wrong file.
• The same pattern can occur for other objects — Duplicate resource, Duplicate output definition, Duplicate provider configuration — with the same underlying cause: a repeated named block within one module.

Common Root Causes

• Same variable in two files: region declared in both variables.tf and network.tf. This is the classic case, common after modularising a large main.tf.
• Merge conflict artifact: a Git merge duplicated a variable block, or two branches each added the same variable.
• Copy-paste a block into the wrong file without deleting the original.
• Confusing declaration with assignment: trying to “override” a variable by adding a second variable block instead of setting its value in a .tfvars file.
• Generated + hand-written files: a codegen step and a human both emit the same variable into different .tf files in the same directory.

Diagnostic Workflow

Let terraform validate name both locations, then grep to confirm every declaration of that name:

terraform validate

# List every declaration of the duplicated variable across the module
grep -rn 'variable "region"' *.tf

# List all variable names to spot other duplicates at a glance
grep -rhn 'variable "' *.tf | sort | uniq -d

Here is a configuration that triggers the error — region is declared in two files that live in the same directory:

# variables.tf
variable "region" {
  type        = string
  description = "AWS region for all resources"
  default     = "us-east-1"
}

# network.tf  <-- duplicate declaration of the same name
variable "region" {
  type    = string
  default = "us-west-2"
}

The fix keeps a single canonical declaration (usually in variables.tf) and deletes the other block:

# variables.tf — the ONLY declaration of "region"
variable "region" {
  type        = string
  description = "AWS region for all resources"
  default     = "us-east-1"
}

# network.tf — variable block removed; just reference var.region here
resource "aws_subnet" "app" {
  # ... uses var.region indirectly via the provider/region wiring
}

If you actually wanted a different value in one environment, do not add a second block — set it in a .tfvars file or with -var:

# Correct way to change a value (not a second declaration)
terraform plan -var 'region=us-west-2'
# or a file: terraform plan -var-file=west.tfvars

Example Root Cause Analysis

A team split a 900-line main.tf into variables.tf, network.tf, and compute.tf. The refactor moved most variable blocks into variables.tf but accidentally left a variable "region" block behind in network.tf while also adding one to variables.tf. The next terraform plan failed:

Error: Duplicate variable declaration

  on network.tf line 3:
   3: variable "region" {

A variable named "region" was already declared at variables.tf:1,1-19.
Variable names must be unique within a module.

Running grep -rn 'variable "region"' *.tf returned two hits — variables.tf:1 and network.tf:3 — confirming the pair the error named. Because both blocks lived in the same module directory, Terraform merged them and hit the duplicate. The team deleted the network.tf block (keeping the fully documented one in variables.tf) and re-ran terraform validate, which passed. Root cause: an incomplete file split during refactoring that left the variable declared in two places. Adding grep -rhn 'variable "' *.tf | sort | uniq -d to CI would have caught it before merge.

Prevention Best Practices

• Keep all input variable declarations in a single variables.tf per module so duplicates are obvious.
• After merges and refactors, run grep -rhn 'variable "' *.tf | sort | uniq -d to detect any repeated variable names.
• Remember the difference between declaring (variable block, must be unique) and assigning (.tfvars/-var, resolved by precedence); change values via tfvars, never a second block.
• Add terraform validate to pre-commit hooks and CI so duplicate declarations fail before merge.
• Watch for merge-conflict duplication; review the whole hunk, not just the conflict markers.
• If a codegen step emits variables, ensure it does not write names that hand-authored files already declare in the same directory.

Quick Command Reference

# Pinpoint both declarations
terraform validate

# Find all declarations of a specific variable
grep -rn 'variable "region"' *.tf

# Detect ANY duplicated variable name in the module
grep -rhn 'variable "' *.tf | sort | uniq -d

# Set a value the correct way (not a second declaration)
terraform plan -var 'region=us-west-2'
terraform plan -var-file=west.tfvars

# Re-validate after removing the duplicate
terraform validate && terraform plan

Conclusion

Duplicate variable declaration means the same variable "<name>" block appears twice in one module — Terraform merges every .tf file in the directory and needs each variable name to be unique. The error conveniently names both locations, so the fix is to keep one canonical declaration (in variables.tf) and delete the other. If you were trying to change a value, use a .tfvars file or -var instead of a second block. A quick uniq -d grep and a terraform validate gate in CI make this a merge-time catch rather than a plan-time failure.