Demo Debugging Terraform

This guide shows how to enable Terraform logging to get detailed diagnostic output when your configuration or provider interactions behave unexpectedly. Use these logs to inspect Terraform core activity (graph transforms, diff processing, provider RPCs) and to gather information you can share with maintainers after scrubbing secrets. Below is a minimal Terraform configuration used for this demo. The specific resources aren’t important for logging; the example simply provides context for the terraform plan output.

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

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

Run a normal plan

Start with the default, concise behavior to compare outputs:

terraform plan

Typical (truncated) summary output:

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.

Enable Terraform logging

Terraform supports the following log levels: TRACE, DEBUG, INFO, WARN, and ERROR. TRACE is the most verbose and is useful when you need deep internals. Use TF_LOG to set the log level and TF_LOG_PATH to write logs to a file. Examples below show platform-specific commands.

macOS / Linux (bash or zsh)

Enable trace logging for the current shell:

export TF_LOG=TRACE

Run the plan again to see detailed trace output:

terraform plan

You will still see the normal plan summary at the end, but the command will include many trace lines showing Terraform core activity, provider registry interactions, graph transforms, diff processing, and provider RPC calls. Example (truncated):

2026-02-14T20:43:00.328-0500 [TRACE] Executing graph transform *terraform.ModuleVariableTransformer
2026-02-14T20:43:00.328-0500 [TRACE] Completed graph transform *terraform.ModuleVariableTransformer (no changes)
2026-02-14T20:43:00.328-0500 [TRACE] Executing graph transform *terraform.variableValidationTransformer
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 complete
2026-02-14T20:43:00.329-0500 [TRACE] Completed graph transform *terraform.DiffTransformer with new graph:
  aws_subnet.private - *terraform.NodeApplyableResourceInstance
  aws_subnet.public - *terraform.NodeApplyableResourceInstance
  aws_vpc.main - *terraform.NodeApplyableResourceInstance

To capture logs to a file (recommended if you will share logs or review them later), set TF_LOG_PATH:

export TF_LOG=TRACE
export TF_LOG_PATH=terraform-debug.log
terraform plan
# Logs will be written to terraform-debug.log

Windows PowerShell

Enable TRACE logging in PowerShell:

# Enable TRACE logging
$env:TF_LOG = "TRACE"
# Optionally capture to a file
$env:TF_LOG_PATH = "C:\path\to\terraform-debug.log"

terraform plan

# To clear the environment variables in PowerShell:
Remove-Item Env:TF_LOG
Remove-Item Env:TF_LOG_PATH

Windows CMD

Set environment variables in CMD:

set TF_LOG=TRACE
set TF_LOG_PATH=terraform-debug.log

terraform plan

rem To unset in CMD:
set TF_LOG=
set TF_LOG_PATH=

Stop logging

When finished debugging, unset TF_LOG (and TF_LOG_PATH if set) to return to normal concise output. On macOS / Linux:

unset TF_LOG
unset TF_LOG_PATH  # if you set it
terraform plan  # now shows regular output

Log level reference

Use the appropriate log level to control verbosity and reduce noise:

Log Level	Typical Use Case	Description
`ERROR`	Routine runs	Surface errors that prevent Terraform from completing.
`WARN`	Routine runs	Highlight potential problems worth investigating.
`INFO`	Diagnostic runs	Higher-level informational messages about operations.
`DEBUG`	Deep debugging	Lower-level implementation details from Terraform and providers.
`TRACE`	Deep debugging / provider issues	Most verbose; shows Terraform core internals, graph transforms, diffs, and provider RPC traffic. Use only when needed.

Avoid sharing logs that may contain secrets, credentials, or sensitive identifiers. Use TF_LOG_PATH to generate a log file you can inspect and sanitize before sharing. If you must send logs to HashiCorp or a provider support team, scrub or redact secrets first.

When to use each level

ERROR / WARN — Good for routine runs to identify failures and warnings.
INFO — Useful for understanding higher-level operations without too much noise.
DEBUG — For investigating implementation-level behavior in Terraform or providers.
TRACE — For the deepest visibility into Terraform core, provider RPCs, graph transforms, and diff internals. Reserve for difficult-to-diagnose issues.

Summary

Using TF_LOG and TF_LOG_PATH helps you inspect Terraform internals (graph transforms, provider communications, validations, diffs) and can provide the necessary detail to debug complex provider or core issues. Always review and redact any sensitive data before sharing logs externally.

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

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Demo Debugging Terraform

Run a normal plan

Enable Terraform logging

macOS / Linux (bash or zsh)

Windows PowerShell

Windows CMD

Stop logging

Log level reference

When to use each level

Summary

Links and references

Watch Video

​Run a normal plan

​Enable Terraform logging

​macOS / Linux (bash or zsh)

​Windows PowerShell

​Windows CMD

​Stop logging

​Log level reference

​Tips for sharing logs

​When to use each level

​Summary

​Links and references

Watch Video

Run a normal plan

Enable Terraform logging

macOS / Linux (bash or zsh)

Windows PowerShell

Windows CMD

Stop logging

Log level reference

Tips for sharing logs

When to use each level

Summary

Links and references