Demo Debugging Terraform

This lesson shows how to enable Terraform’s logging to get detailed debugging information when troubleshooting configuration or provider issues. Detailed logs can reveal internal graph transforms, provider attachment, HCL source locations, and diff analysis that help diagnose misconfigurations, provider matching problems, or communication errors.

Minimal demo configuration

Below is the minimal Terraform configuration used for the demo:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.31.0"
    }
  }

  required_version = ">= 1.2.2"
}

provider "aws" {
  region = "us-east-2"
}

Running a normal plan typically produces a concise summary:

$ terraform plan
Plan: 3 to add, 0 to change, 0 to destroy.

Note: You didn't use the --out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.

When to enable logging

Enable Terraform logging when you need more visibility into what Terraform Core and providers are doing — for example, when:

Providers fail to match or load.
Resources unexpectedly change or are omitted from the graph.
API calls to providers return errors and you need the request/response context.

The most verbose output level is TRACE.

TF_LOG levels

Level	Description
`ERROR`	Only error messages
`WARN`	Warnings and errors
`INFO`	High-level informational messages
`DEBUG`	Detailed debugging messages from Terraform and providers
`TRACE`	Most verbose; internal operations, graph transforms, HCL ranges, provider interactions

See the official environment variables reference for Terraform logging: Terraform CLI — Environment variables.

Enable verbose logging

On macOS / Linux (bash/zsh):

export TF_LOG=TRACE
# optional: write logs to a file instead of STDOUT
export TF_LOG_PATH=./terraform.log

On Windows PowerShell:

$env:TF_LOG = "TRACE"
# optional: write logs to a file
$env:TF_LOG_PATH = "C:\temp\terraform.log"

After enabling TRACE and running terraform plan, you will observe many more internal messages. The excerpts below are representative: they show Terraform’s graph transforms, provider matching, HCL source ranges, and diff decisions.

2026-02-14T20:43:00.330-0500 [TRACE] Completed graph transform *terraform.TargetsTransformer
2026-02-14T20:43:00.330-0500 [TRACE] Executing graph transform *terraform.ephemeralResourceTransformer
2026-02-14T20:43:00.330-0500 [TRACE] Completed graph transform *terraform.ephemeralResourceTransformer
2026-02-14T20:43:00.330-0500 [TRACE] Executing graph transform *terraform.CloseProviderTransformer
2026-02-14T20:43:00.330-0500 [TRACE] Completed graph transform *terraform.CloseProviderTransformer

2026-02-14T20:43:00.329-0500 [TRACE] (graphTransformerMulti) Executing graph transform *terraform.transformer
2026-02-14T20:43:00.329-0500 [TRACE] ProviderTransformer: exact match for provider["registry.terraform.io/hashicorp/aws"] serving aws_subnet.private (expand)
2026-02-14T20:43:00.329-0500 [DEBUG] ProviderTransformer: "aws_subnet.private (expand)" (*terraform.nodeExpandApplicableResource) needs provider["registry.terraform.io/hashicorp/aws"]
2026-02-14T20:43:00.329-0500 [TRACE] ProviderTransformer: exact match for provider["registry.terraform.io/hashicorp/aws"] serving aws_subnet.public
2026-02-14T20:43:00.329-0500 [DEBUG] ProviderTransformer: "aws_subnet.public" (*terraform.nodeApplyableResourceInstance) needs provider["registry.terraform.io/hashicorp/aws"]

You will also see resource attachment and HCL source references, which are useful for pinpointing the source file and location for a resource:

2026-02-14T20:43:00.329-0500 [TRACE] AttachResourceConfigTransformer: attaching provider to aws_subnet.public
2026-02-14T20:43:00.329-0500 [TRACE] AttachResourceConfigTransformer: attaching to "aws_subnet.private" (*terraform.NodeApplicableResourceInstance) config from hcl.Range{Filename: "main.tf", Start:hcl.Pos{Line:11, Column:1, Byte:202}, End:hcl.Pos{Line:11, Column:32, Byte:233}}
2026-02-14T20:43:00.329-0500 [TRACE] AttachResourceConfigTransformer: attaching provider to aws_subnet.private
2026-02-14T20:43:00.329-0500 [TRACE] AttachResourceConfigTransformer: attaching to "aws_vpc.main" (*terraform.NodeApplicableResourceInstance) config from hcl.Range{Filename: "main.tf", Start:hcl.Pos{Line:1, Column:1, Byte:0}, End:hcl.Pos{Line:1, Column:26, Byte:25}}
2026-02-14T20:43:00.329-0500 [TRACE] Completed graph transform *terraform.AttachResourceConfigTransformer (no changes)

Diff determination and change representation are also logged:

2026-02-14T20:43:00.329-0500 [TRACE] DiffTransformer: found Create change for aws_subnet.private
2026-02-14T20:43:00.329-0500 [TRACE] DiffTransformer: aws_subnet.private will be represented as create
2026-02-14T20:43:00.329-0500 [TRACE] DiffTransformer complete
2026-02-14T20:43:00.329-0500 [TRACE] Completed graph transform *terraform.DiffTransformer

These traces make it easier to locate where Terraform is assigning providers, how it builds the resource graph, and why particular resources are created, changed, or left unchanged.

TRACE logs can include sensitive data (like provider tokens, API keys, or resource attributes). Avoid sending raw trace logs to third parties without sanitizing them first.

If you must share logs with HashiCorp or a provider, redact secrets (API keys, tokens, passwords, and any sensitive attributes) before uploading. Consider limiting logs to a file and opening it in a secure editor to mask secrets.

Disable logging when finished

When you’ve captured the necessary information, turn logging off to restore concise output.

On macOS / Linux:

unset TF_LOG
# optionally unset TF_LOG_PATH
unset TF_LOG_PATH

On Windows PowerShell:

Remove-Item Env:\TF_LOG
# optionally:
Remove-Item Env:\TF_LOG_PATH

After unsetting, terraform plan returns to the normal concise output:

$ terraform plan
Plan: 3 to add, 0 to change, 0 to destroy.

Note: You didn't use the --out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.

References

Thanks for following this lesson.

Watch Video

Debugging Terraform

HCP Terraform Overview longer video

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Demo Debugging Terraform

Minimal demo configuration

When to enable logging

TF_LOG levels

Enable verbose logging

Disable logging when finished

References

Watch Video

​Minimal demo configuration

​When to enable logging

​TF_LOG levels

​Enable verbose logging

​Disable logging when finished

​References

Watch Video

Minimal demo configuration

When to enable logging

TF_LOG levels

Enable verbose logging

Disable logging when finished

References