Debugging unexpected issues with Terraform

17 July 2023

Since Terraform is relatively new software, you might need to fix issues in a undocumented way. You can spend hours debugging internal providers this way but there are a couple of ways that can help you fix issues faster.

Error: Unsupported argument

When using modules from the Terraform registry, you’ll mostly encounter this error, which then triggers the following error:

An argument named "xyz" is not expected here.

Often, this implies that your Terraform version isn’t compatible with the module version. For instance, they’ve only tested module 1.0.0 with Terraform 1.11, but you’re currently running Terraform 1.09.

Try upgrading or downgrading the module version first. If that does not work try upgrading or downgrading your Terraform. Upgrading Terraform risks that other modules that you have might stop working.

After you upgrade the module version in your terraform files you must run:

terraform init -upgrade

Currently Terraform does not have a similar support like composer.json. This would allow modules to tell Terraform which versions of Terraform it can support.

Currently it is a best practice to align the Terraform versions across your team and to pin your module versions:

module "iam" {
  source  = "terraform-aws-modules/iam/aws"
  version = "5.27.0"

Corrupt local module

In some cases there is an issue where some modules have corruption in your local folder. If you run a terraform init then it will create the following folder structure:

  • .terraform – This folder holds the downloaded modules and providers from the registry. Often modules depend on other modules so this folder can become quite large.
  • .terraform.lock.hcl – This file locks the versions to your Terraform project and should be committed to your source repository

In some cases it can help to delete this .terraform folder and reinitialise this folder by using terraform init.

Unsupported module operation

Some modules might be built in a certain way that supports a single mode of operation at a time (but the module supports two modes of operation in total).

Building modules in Terraform is highly complex so it is easy to overlook an edge case. In this case you might have setup a resource in mode A and try to update the resource to mode B. This will then fail with a vague error message.

If you delete this resource first and then recreate it in mode B, often this will work.

Recent articles:

Reduce AWS Fargate pull times with SOCI

Read more >

Reduce your AWS CloudFront costs by switching to Cloudflare

Read more >

Cross account AWS KMS keys

Read more >

Need an AWS Expert?

Plan a free meeting now, no strings attached.