Enabling trace-level logs in HCP Terraform, Terraform Enterprise and Terraform CLI

Introduction

This guide provides instructions for enabling trace-level logs in HCP Terraform, Terraform Enterprise, and the Terraform CLI. Setting the TF_LOG environment variable to TRACE generates detailed logs that are useful for debugging complex issues with Terraform runs.

Procedure

Follow the method appropriate for your Terraform edition and use case.

Method 1: Enable for a Single Run in HCP Terraform or Terraform Enterprise

This method enables trace logging for a single run directly from the user interface. This feature is available in Terraform Enterprise v202502-2 or later and in all HCP Terraform tiers.

1. Navigate to the Overview page of the desired workspace.
2. Select New Run to start a new run.
3. Configure the Run Name and Run Type as needed.

4. Expand Additional Planning Options and toggle Enable Debug Logging.

   

   Note: Enabling trace logging this way applies it to the current run only. You must re-enable it for any subsequent runs.

5. Select Start Run.

Method 2: Enable via Workspace Variables in HCP Terraform or Terraform Enterprise

This method uses an environment variable within the workspace to enable trace logging for all subsequent runs until the variable is removed.

1. Navigate to your workspace's Settings > General page.

2. In the User Interface section, select Console UI.

   

3. Navigate to Variables and select Add variable.

4. Create a new Environment Variable with the following values:

   • Key: TF_LOG
   • Value: TRACE

   

5. Start a new run. You can view the detailed logs by selecting View raw log.

   

After you finish debugging, delete the TF_LOG environment variable from the workspace variables to disable trace logging.

Method 3: Enable for Terraform CLI on Unix, Linux, or macOS

1. Set the TF_LOG environment variable to TRACE in your terminal.

   $ export TF_LOG="TRACE"

2. Run the Terraform operation you wish to debug. Redirect standard output and standard error to a log file using 2>&1 and disable ANSI color escape sequences with the -no-color flag.

   $ terraform plan -no-color 2>&1 | tee plan.log

3. After you finish debugging, unset the environment variable.

   $ unset TF_LOG

Method 4: Enable for Terraform CLI on Windows

1. Set the TF_LOG environment variable to TRACE in your PowerShell terminal.

   $Env:TF_LOG="TRACE"

2. Run the Terraform operation you wish to debug. Redirect standard output and standard error to a log file and disable ANSI color escape sequences with the -no-color flag.

   $ terraform plan -no-color 2>&1 | Tee-Object -FilePath plan.log

3. After you finish debugging, remove the environment variable.

   $Env:TF_LOG=""

Additional Information

For more details on debugging Terraform, refer to the official documentation on Debugging Terraform.