How to fix Error: An argument named X is not expected here. Did you mean Y? in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 30, 2025· 143 views

This error occurs when Terraform configuration contains invalid or unsupported arguments in resources, modules, or variables. Fix it by verifying argument names against provider documentation, checking module variable definitions, and updating deprecated arguments.

Quick fix

Fixes Error: An argument named X is not expected here. Did you mean Y?

terraform init -upgrade
  1. Run terraform init -upgrade to ensure latest provider versions
  2. Check the suggested argument name from the error message
  3. For modules: verify variables.tf declares the argument
  4. Check provider documentation for version-specific arguments
terraform — error
terraform init -upgrade
Error: An argument named X is not expected here. Did you mean Y?

What this error means

The "argument not expected" error means that Terraform encountered an argument (configuration key) that doesn't exist or isn't recognized in the current context. This typically happens in three scenarios: 1. **Module variable mismatch**: You're passing an argument to a module that doesn't declare a corresponding variable in its `variables.tf` file. 2. **Provider version incompatibility**: You're using an argument that was deprecated, renamed, or removed in a newer provider version. For example, `number_cache_clusters` might have been renamed to `num_cache_clusters`. 3. **Syntax errors**: You're using incorrect block syntax where Terraform expects an argument assignment (with `=` sign), or vice versa. Terraform's "Did you mean Y?" suggestion appears when it detects a similar argument name, helping you quickly fix typos or outdated argument names.

Typical symptoms

  • terraform plan or terraform apply fails before reaching actual infrastructure changes
  • Error message lists the unexpected argument name and sometimes suggests a correction
  • Issue occurs during module instantiation or resource configuration
  • Problem appears after upgrading Terraform version or provider version
  • Works in one environment but fails in another (version mismatch between environments)

Common causes

  1. Variable not declared in the child module's variables.tf when passing arguments to a module
  2. Provider upgrade introduced breaking changes that renamed or removed arguments
  3. Outdated provider documentation or configuration from older Terraform versions
  4. Typo in argument name or mixing up argument names across different resource types
  5. Using block syntax (curly braces) instead of argument syntax (equals sign) or vice versa

How to fix "Error: An argument named X is not expected here. Did you mean Y?"

1Run terraform init -upgrade to ensure latest provider versions

Update your provider locks to the latest compatible versions. This helps identify version-specific argument changes:

bash
terraform init -upgrade

This refreshes your .terraform.lock.hcl file and downloads the latest provider versions. After this, run terraform validate to see if the issue persists or resolves.

2Check the suggested argument name from the error message

Terraform often suggests the correct argument name. If the error says "Did you mean X?", update your configuration to use X instead.

For example, if you see:

bash
Error: An argument named "number_cache_clusters" is not expected here. Did you mean "num_cache_clusters"?

Update your code:

hcl
# Wrong
resource "aws_elasticache_replication_group" "example" {
  number_cache_clusters = 3
}

# Correct
resource "aws_elasticache_replication_group" "example" {
  num_cache_clusters = 3
}
3For modules: verify variables.tf declares the argument

If you're passing arguments to a module, ensure the child module declares them as variables:

hcl
# In your root module
module "example" {
  source = "./modules/example"

  custom_argument = "value"  # ERROR: this arg must be declared in module
}

# Fix: add to modules/example/variables.tf
variable "custom_argument" {
  type        = string
  description = "Description of the argument"
}

# Then use it in the module's main.tf
resource "some_resource" "example" {
  name = var.custom_argument
}
4Check provider documentation for version-specific arguments

Visit the official provider documentation and verify the argument name and type for your provider version.

For AWS Provider:
- Go to https://registry.terraform.io/providers/hashicorp/aws/latest
- Find your resource type
- Check the "Argument Reference" section for exact names

For other providers, replace aws with your provider name at https://registry.terraform.io/

If upgrading a provider, check the changelog for breaking changes or deprecated arguments:

bash
# View provider version info
terraform version

Update your required_providers block if needed:

hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Update to desired version
    }
  }
}
5Validate your configuration and review full error output

Run terraform validate to catch errors early and get detailed diagnostics:

bash
terraform validate

For more detailed error information, enable debug logging:

bash
TF_LOG=DEBUG terraform plan 2>&1 | head -100

The full error output often shows the exact line and resource causing the issue, making it easier to pinpoint the problem.

Advanced notes

Module Variable Caching: After updating module variables, Terraform may still use cached module metadata. Clear the cache by deleting the .terraform directory and running terraform init again:

bash
rm -rf .terraform
terraform init

Provider Breaking Changes: Major provider version upgrades frequently introduce breaking changes. Always review the changelog before upgrading. For example, AWS Provider 5.0 had significant argument renames and reorganizations. Test upgrades in a non-production environment first.

Block vs Argument Syntax: Terraform 0.12+ requires different syntax:
- Arguments (most resource settings): use = sign (e.g., name = "value")
- Blocks (nested structures): use no = sign (e.g., tags { ... })

If you see "Blocks of type 'X' are not expected here. Did you mean to define argument 'X'?", add an equals sign to convert it to an argument.

Cross-Module References: When modules reference variables from parent modules, ensure the variable is properly passed through. Use var.variable_name syntax and verify the variable is declared in all intermediate variables.tf files.

Frequently asked questions

What does "Error: An argument named X is not expected here. Did you mean Y?" mean?
The "argument not expected" error means that Terraform encountered an argument (configuration key) that doesn't exist or isn't recognized in the current context. This typically happens in three scenarios: 1. tf file.
How do I fix "Error: An argument named X is not expected here. Did you mean Y?"?
This error occurs when Terraform configuration contains invalid or unsupported arguments in resources, modules, or variables. Fix it by verifying argument names against provider documentation, checking module variable definitions, and updating deprecated arguments.
What causes "Error: An argument named X is not expected here. Did you mean Y?"?
Variable not declared in the child module's variables.tf when passing arguments to a module Provider upgrade introduced breaking changes that renamed or removed arguments Outdated provider documentation or configuration from older Terraform versions
Is the "Error: An argument named X is not expected here. Did you mean Y?" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading