> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demo Debugging Terraform

> How to enable and use Terraform logging for detailed TRACE debugging, including configuration, log setup, interpreting traces, and redacting sensitive data

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:

```hcl theme={null}
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:

```bash theme={null}
$ 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](https://developer.hashicorp.com/terraform/cli/config/environment-variables#tf_log).

## Enable verbose logging

* On macOS / Linux (bash/zsh):

```bash theme={null}
export TF_LOG=TRACE
# optional: write logs to a file instead of STDOUT
export TF_LOG_PATH=./terraform.log
```

* On Windows PowerShell:

```powershell theme={null}
$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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

<Callout icon="lightbulb" color="#1CB2FE">
  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.
</Callout>

<Callout icon="warning" color="#FF6B6B">
  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.
</Callout>

## Disable logging when finished

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

* On macOS / Linux:

```bash theme={null}
unset TF_LOG
# optionally unset TF_LOG_PATH
unset TF_LOG_PATH
```

* On Windows PowerShell:

```powershell theme={null}
Remove-Item Env:\TF_LOG
# optionally:
Remove-Item Env:\TF_LOG_PATH
```

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

```bash theme={null}
$ 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

* [Terraform CLI — Environment variables (TF\_LOG)](https://developer.hashicorp.com/terraform/cli/config/environment-variables#tf_log)
* [Terraform CLI — plan command](https://developer.hashicorp.com/terraform/cli/commands/plan)

Thanks for following this lesson.

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/hashicorp-certified-terraform-associate-004/module/5a3363d1-83cc-4a39-997d-82fa687251ac/lesson/745b1ae5-da9e-4c2f-8c70-9b21c811d6f4" />
</CardGroup>