Debugging in Terraform is a vital skill every developer and DevOps engineer should master. Whether you’re new to infrastructure as code or managing complex multi-cloud systems, being able to diagnose issues quickly can save you hours of frustration.
This guide explains how to debug Terraform effectively using environment variables, logging levels, and trace files—so you can resolve problems faster and keep your infrastructure running smoothly.
Table of Contents
Why Debugging in Terraform Matters
When Terraform commands like apply, plan, or init fail, they usually provide some output to help identify the cause. However, there are times when this standard output isn’t enough.
That’s where enabling debugging in Terraform comes into play. By increasing the logging verbosity, you can uncover internal behaviors and plugin interactions that are otherwise hidden. This allows you to pinpoint misconfigurations, provider issues, or even bugs in Terraform itself.
How to Enable Debugging in Terraform
Using TF_LOG Environment Variable
Terraform provides a built-in environment variable called TF_LOG that controls the logging level. You can set it to different verbosity levels depending on your debugging needs.
Available log levels:
TRACE: Shows every internal operation. Most verbose.DEBUG: Detailed information including plugin actions.INFO: General operational messages.WARN: Warnings about potential issues.ERROR: Only displays actual errors.OFF: No logs are shown (default if unset).
To enable debugging, export the desired log level before running your command:
export TF_LOG=DEBUG
terraform apply
Once set, the console will display more granular information. This can help in identifying subtle misbehaviors, such as mismatched resource arguments or plugin incompatibilities.
Logging with TRACE for Deep Diagnostics
If standard logs don’t surface the problem, setting TF_LOG=TRACE provides the most detailed output, including low-level plugin operations and internal data handling.
export TF_LOG=TRACE
terraform plan
Running this command may produce thousands of lines of output. While verbose, this mode is especially helpful when diagnosing provider bugs or unexpected behaviors deep within Terraform’s core engine.
You can also use this log output when reporting issues to the Terraform development team, as it helps reproduce and understand your problem.
Saving Debug Logs to a File
Printing debug logs to the terminal can be overwhelming and hard to follow. To preserve logs and inspect them more easily, Terraform allows redirecting logs to a file using the TF_LOG_PATH variable.
Here’s how:
export TF_LOG=DEBUG
export TF_LOG_PATH=./terraform-debug.log
terraform apply
This saves all logs to the file terraform-debug.log in your working directory. You can now review, filter, or share this file with your team or support staff.
Saving logs is also crucial for troubleshooting production issues, postmortems, or documentation purposes.
How to Disable Debugging
Once you’re done investigating, it’s good practice to disable Terraform debugging. Leaving verbose logging on may clutter your console or fill up disk space over time.
To turn off debugging, simply unset the environment variables:
unset TF_LOG
unset TF_LOG_PATH
Terraform will now operate with its default behavior, displaying only essential output.
Best Practices for Debugging in Terraform
1. Start with Lower Log Levels
Begin with INFO or DEBUG. Jump to TRACE only when needed. This prevents information overload and makes logs more manageable.
2. Always Log to a File for Long Sessions
Using TF_LOG_PATH ensures you don’t miss important details due to scrolling limitations in the terminal.
3. Filter Logs with Tools Like grep or jq
For example:
grep 'aws_instance' terraform-debug.log
This helps locate specific resource logs quickly.
4. Reset Environment Variables After Use
Always unset logging variables when finished to keep your environment clean.
Common Use Cases for Debugging
Diagnosing Resource Creation Failures
If a resource fails to provision but the error message isn’t clear, enable debug logging to trace the cause.
Investigating Plugin Issues
Plugins used by providers may misbehave. TRACE logs reveal how they interact with Terraform during apply.
Reporting Bugs
Detailed logs are invaluable when reporting problems to Terraform maintainers or plugin developers.
Conclusion
Debugging in Terraform is essential for reliable and consistent infrastructure deployments. By leveraging TF_LOG and TF_LOG_PATH, you gain deeper visibility into your configurations, making it easier to identify and resolve issues.
Whether you’re fixing a failed apply or troubleshooting a complex module, using Terraform’s logging features properly will make you more effective and confident in managing infrastructure as code.
Don’t overlook this feature—it’s your first line of defense when things go wrong.
Frequently Asked Questions (FAQ)
1. What is TF_LOG in Terraform?
TF_LOG is an environment variable used to set the verbosity level of Terraform’s internal logging. It helps in debugging and troubleshooting.
2. What are the different log levels in Terraform?
Terraform supports TRACE, DEBUG, INFO, WARN, and ERROR. Each level controls how much detail is logged during execution.
3. How do I save logs to a file?
Use the TF_LOG_PATH variable to define a file path. Logs will be written to that file instead of the terminal.
4. Can I leave TF_LOG enabled always?
It’s not recommended. Continuous verbose logging can impact readability and system performance. Always unset it when done.
5. Is TRACE logging safe in production?
TRACE can expose sensitive internal information. Use it with caution and restrict access to the log files.