Terraform Debug

Terraform Debug

It doesn’t matter which project or technologies you use to build your environment or application. Debugging is a skill that we always need to improve, and it saves us a lot of time when we can get to the root cause faster. When I built my first cloud resources in the cloud using Terraform, I ran into many problems, and it was hard to figure out what was going on. Today, I would like to share some experiences that I had in the past and how I used the features that Terraform provided us to debug our code on the plan and apply phases.

Many API calls happen behind the scene when we execute “terraform plan” or “terraform apply” many API calls are done behind the scene. Those calls reach your cloud provider. For example, Terraform uses the AWS SDK to make those calls if you use AWS.

Let’s learn how to see and analyze those calls and see the different debug levels. Each level has a particular amount of detail, and honestly, we only enable those features when we need them. Because it throws many lines and is fast, it’s almost impossible to read, but we can save the output and analyze it more deeply later.

Terraform Debug Process

To make our life easier, we must be aware of how the Terraform works by parts and see what each piece does to identify the location that may be the issue. 

Terraform Debug - Tips
Terraform Debug

The diagram above shows us our process slipt into four parts. Let’s learn the scope of each piece and see what happens on each one.

For each part: Provider, Core, State, and Language, we can enable logging individually. That makes it easier to quickly isolate the error and find the root cause.

Debug Terraform Language Errors:

The Terraform uses the HashiCorp Configuration Language (HCL). Error on this level, if the process by the Terraform Core, like a syntax error.

Terraform provides a command line that helps us check the HCL before trying to execute the terraform plan or apply.


terraform fmt

The command above could be executed at any time to find interpolation mistakes or malformed resource definitions.

Terraform State Errors

The terraform state stores, map our resources in the cloud, and generates all metadata. Error on this level, like a mismatch (out of sync) between the state and resource in the cloud, could make Terraform destroy your resource.

Terraform Core Errors

The core is where all validations happen for all operations. For example, we validate the syntax, handle changes in the state, and manage the communication with the Provider SDK.

Terraform Provider Erros

The Provider SDK handles all API calls necessary to map the resources and authentication.

Let’s see how we can debug and validate Terraform on the cloud provider side:

We can run the command below to validate our changes and check all cloud-provided resources and rules. For example, if you have specified an AWS Security Group that doesn’t exist in your EC2 instances.


terraform validate

The command above it’s very useful for extensive configuration. I have already worked on a big project that takes a lot of time on the “plan” and the “apply” phase. So we can quickly get all errors that may appear on the cloud provider side instead of waiting for the completion of the “apply” or “plan” phase.

Knowing those parts, we can now see how to take advantage of the Environment Variables that Terraform has available to enable the logs separately for each of those parts.

Terraform Debug – Environment Variables

The approach to enable the debug or verbose provides an environment on your terminal.

For example:

TF_LOG, it’s the major environment variable to enable the Terraform Debug.


Terraform Debug – Level

TF_LOGsupports more levels like INFO, TRACE, WARN
INFOThis Terraform Debug Level shows generic and not-so-deep details about the execution process.
DEBUGOn this level is the most details log that you can use. It shows all internal calls, and it’s better than the TRACE level.
TRACEThis level shows Terraform’s steps and generates a massive amount of logs.
ERRORDisplays problems that block Terraform from succeeding.
WARNThis level shows only warnings logs, which may suggest misconfiguration or missteps, while are not vital to execution.

How to Persist Log on Terraform

So, we know how to enable the logs and choose which level of details we may want to improve our debug process on Terraform.

But, because Terraform generates a considerable amount of logs, it sometimes makes sense to save them to a file to be able to analyze later or share with someone for support.

We can use the TF_LOG_PATH to indicate where we want to save the logs. For example

export TF_LOG_PATH=./.terraform/log

It’s worth remembering that to use the TF_LOG_PATH, the TF_LOG must be specified to enable the logs.

Terraform Debug: Provider

How to enable logs for our Cloud Provider?

Terraform allow us to enable another set of logs to show us all API calls and steps to mapping the resources with our cloud provider. To achieve that, we can specify the TF_LOG_PROVIDER environment variable.

Also, we can use the same debug levels that we have learned above to TF_LOG for TF_LOG_PROVIDER.

How to debug the Terraform Core?

We can use the environment variable TF_LOG_CORE to start logging information and details that occur on the Terraform Core. Regarding the levels of logs, we can also use the same level shown before.


Thanks for visiting us! I hope you find helpful information in this article that will save you a bunch of time. If you find any bug on Terraform, you can report it on GitHub’s Official repository.

Leave a Comment

Your email address will not be published. Required fields are marked *

Free PDF with a useful Mind Map that illustrates everything you should know about AWS VPC in a single view.