Skip to main content
In this lesson we focus on debugging Terraform runs. The goal is to give you practical, repeatable steps to enable logging, interpret messages, and resolve failures quickly. Below are the objectives we’ll cover, presented in sequence:
The image is an introduction to Terraform logging with four main points about understanding logging, enabling debug logs, interpreting error messages, and identifying causes of failures. It is designed with a gradient background on the left and numbered sections on the right.
This is a short, practical lesson. Enabling Terraform logging is simple — the real value comes from knowing which log level to use, how to capture output safely, and how to read key sections of the logs to find the root cause.
Quick tip: start with TF_LOG=ERROR or TF_LOG=WARN for targeted problems. Increase to DEBUG or TRACE only when you need detailed provider or RPC-level traces, because higher levels produce a lot of noise.

​
How to enable debug logs

Use the TF_LOG environment variable to set the verbosity and TF_LOG_PATH to write logs to a file instead of flooding the console. Bash (Linux / macOS):
PowerShell (Windows):
Common TF_LOG levels:
  • TRACE — very verbose; includes HTTP requests and detailed internals.
  • DEBUG — developer-level debug information.
  • INFO — general progress and informational messages.
  • WARN — warnings about potential issues.
  • ERROR — only errors.
If you prefer console output only, omit TF_LOG_PATH and let the logs stream to stdout. To keep CI logs manageable, always set TF_LOG_PATH and rotate or archive logs.

​
Practical capture & search workflow

  1. Reproduce the failing command (e.g., terraform plan or terraform apply) with TF_LOG set.
  2. Save logs to TF_LOG_PATH so you can inspect and share selectively.
  3. Search for high-level markers first:
    • ERROR and WARN entries
    • Provider response payloads or HTTP status codes
    • State-related messages such as locks or conflicts
  4. If necessary, increase to TRACE and re-run only the failing action to limit volume.
Example useful searches:

​
Common error sources and where to look

  • Configuration syntax or validation errors — often shown directly in Terraform CLI output (check terraform validate).
  • Provider authentication/authorization failures — inspect provider init/auth sections in logs.
  • Remote state and lock conflicts — look for state backend messages and lock acquisition attempts.
  • Provider or API errors — TRACE/DEBUG show HTTP responses and request payloads for APIs.
  • Resource dependencies and lifecycle issues — check planning output and graph-related messages.
Use this checklist during troubleshooting:
  • Can you reproduce the failure locally?
  • Did you validate the configuration (terraform validate)?
  • Is provider authentication current (tokens, service principal, credentials)?
  • Is the remote state reachable and unlocked?

​
Systematic debugging steps

  1. Reproduce with the minimal command and configuration.
  2. Run terraform validate and terraform plan without debug first — many issues are visible here.
  3. Enable TF_LOG=DEBUG and set TF_LOG_PATH to capture logs.
  4. Inspect terraform.log: start with ERROR/WARN, then expand to provider-specific sections.
  5. If you find sensitive data in the logs, redact before sharing with others or support.
  6. If needed, increase to TRACE for deeper protocol-level details and provider internals.

​
References and further reading

Warning: Terraform debug logs can contain sensitive data (API tokens, secrets, or resource attributes). Avoid publishing raw logs publicly. Redact secrets before sharing with colleagues or support.

Watch Video