Andrew Mercer
on this page

Debugging workflow

  1. Read the whole error. Terraform errors name the file, line, address and usually the attribute. Provider errors include the API's response; the useful part is often at the end.
  2. Isolate: which resource, which provider, plan or apply?
  3. Look at the plan for that resource only.
  4. Evaluate expressions in terraform console.
  5. Turn on logging for that one command, to a file.
  6. Reproduce small: a scratch root module with just the failing resource.

Focus on one resource in a plan

ADDR='azurerm_linux_web_app.this["billing"]'

# Human-readable: the block for that resource (grep -F: brackets aren't a regex class)
terraform plan -no-color -out=tfplan > plan.txt
grep -F -A 60 "# ${ADDR}" plan.txt

# Machine-readable: exact before/after for that resource
terraform show -json tfplan \
  | jq --arg a "$ADDR" '.resource_changes[] | select(.address == $a) | {actions: .change.actions, before: .change.before, after: .change.after}'

# Only the attributes that differ
terraform show -json tfplan | jq --arg a "$ADDR" '
  .resource_changes[] | select(.address == $a) | .change as $c
  | [($c.after // {}) | keys[] | select($c.before[.] != $c.after[.])]'

Logging

TF_LOG=DEBUG TF_LOG_PATH=./tf-debug.log terraform apply tfplan
grep -F 'azurerm_linux_web_app.this' tf-debug.log | less

# Provider only (API requests/responses), core quiet
TF_LOG_CORE=ERROR TF_LOG_PROVIDER=DEBUG TF_LOG_PATH=./provider.log terraform plan

Levels: TRACE > DEBUG > INFO > WARN > ERROR. Debug logs contain request bodies, tokens and secrets. Delete them when you're done; never paste them unredacted into issues or chat, and don't enable them in shared CI logs.

Inspect state for one resource

terraform state show 'azurerm_linux_web_app.this["billing"]'
terraform state show -json 'azurerm_linux_web_app.this["billing"]' | jq .   # 1.16+

Common errors

State is locked

Error: Error acquiring the state lock
Lock Info:
  ID:        3f1c...
  Who:       runner@gitlab-runner-7
  Created:   2026-11-09 14:02:11 UTC

Someone or something is running. Check CI for an active job on that stack. If the holder really died (cancelled job, killed laptop session): terraform force-unlock 3f1c.... In CI, use -lock-timeout=5m and serialise jobs per state (CI/CD).

Authentication failures

Error: building account: could not acquire access token to parse claims
Error: Unable to list provider registration status ... AuthorizationFailed
  • Locally: az account show, right tenant/subscription? az login again.
  • subscription_id is required in the azurerm provider block (or ARM_SUBSCRIPTION_ID) since azurerm 4.0.
  • CI with OIDC: is ARM_USE_OIDC=true set, does the job have an id_tokens entry, and does the federated credential's subject match the project/branch/environment exactly?
  • AuthorizationFailed on a specific action: the identity lacks that RBAC permission. The error names the action (Microsoft.Network/virtualNetworks/subnets/join/action).
  • Storage data-plane errors with shared_access_key_enabled = false: set storage_use_azuread = true on the provider and grant a Storage Blob Data role.

for_each / count value depends on resource attributes

Error: Invalid for_each argument
The "for_each" map includes keys derived from resource attributes that cannot be determined until apply

The keys come from something computed. Key by configuration values instead (loops). As a one-time bootstrap only: terraform apply -target= the producer first.

Cycle

Error: Cycle: azurerm_network_security_group.this, azurerm_network_security_rule.allow_lb

Two objects reference each other, possibly through locals, module outputs or depends_on. Find the loop with terraform graph and break it: split a resource into two (inline rules → separate rule resources), or move a shared value into a variable (dependencies).

Perpetual diff / plan noise

A plan shows the same change every run, even right after apply.

Cause Fix
The API normalises a value (case, JSON key order, trailing slash) Write it in the normalised form; jsonencode() for JSON
The service injects a default (e.g. Azure adding a default virtual_application block to App Service) Declare the default explicitly in configuration; better than ignore_changes, which also hides real changes
Another system owns the attribute (Policy tags, autoscaler) ignore_changes on that attribute only, with a comment
timestamp(), uuid(), bcrypt() in an argument plantimestamp(), time_static, random_uuid, stored values
Provider bug Search the provider's GitHub issues; pin a fixed version; temporary ignore_changes with an issue link

Find exactly which attribute flaps with the jq "attributes that differ" query above.

Resource already exists

Error: A resource with the ID "/subscriptions/.../resourceGroups/rg-app-prod" already exists -
to be managed via Terraform this resource needs to be imported into the State.

Something created it outside this state (portal, another stack, a previous failed apply that wasn't recorded). Decide who owns it; if it's this stack, add an import block (refactoring).

Provider produced inconsistent result after apply

Error: Provider produced inconsistent result after apply
When applying changes to azurerm_x.y, provider "registry.terraform.io/hashicorp/azurerm"
produced an unexpected new value: .some_attribute: was "A", but now "B".
This is a bug in the provider, which should be reported in the provider's own issue tracker.

It is a provider bug, as the message says. Usually the resource was created. Run plan again: it typically shows a small update or nothing. Check for an existing issue, upgrade the provider, or work around with explicit values.

Saved plan is stale

Error: Saved plan is stale
The given plan file can no longer be applied because the state was changed by another operation after the plan was created.

Another apply ran in between. Re-plan, re-review, apply. This is protection working as intended.

Lock file checksum mismatch

Error: Failed to install provider
... the local package for registry.terraform.io/hashicorp/azurerm 4.42.0 doesn't match any of the checksums previously recorded in the dependency lock file

The lock file only has hashes for another platform (Linux CI vs a Mac), or the plugin cache holds a different build. Add hashes for every platform: terraform providers lock -platform=linux_amd64 -platform=darwin_arm64 ... (providers).

Module not installed / backend changed

Error: Module not installed
Error: Backend initialization required, please run "terraform init"
Error: Backend configuration changed

Run terraform init (add -upgrade after changing versions, -reconfigure when switching between partial backend configs, -migrate-state when actually moving state).

Variables not allowed

Error: Variables not allowed
  on backend.tf line 4, in terraform:

Terraform's backend block takes literals only. Use partial configuration (-backend-config), Terragrunt, or OpenTofu 1.8+ early evaluation (remote state). Module source/version accept variables from Terraform 1.15.

terraform validate fails on the backend in CI (1.15+)

Since 1.15, validate checks the backend block, so CI jobs that supply backend settings only at init time can fail. Run terraform init -backend=false before validate, or validate in a job that has the backend configuration.

Azure Policy denial

RequestDisallowedByPolicy: Resource 'stapp001' was disallowed by policy.
Policy identifiers: '[{"policyAssignment":{"name":"Deny public storage"...

An Azure Policy Deny assignment blocked the request mid-apply. Fix the configuration to comply, or request an exemption. Mirror important deny rules in CI policy so they fail at plan time instead (policy).

Throttling (429) and timeouts

Error: ... StatusCode=429 ... Too Many Requests
Error: context deadline exceeded

Lower -parallelism (default 10), split large states, and check the provider's retry and timeout settings. Many resources accept a timeouts { create = "60m" } block for slow operations. With Terragrunt, an errors { retry ... } block can retry known transient errors.

Unsupported attribute / argument after a provider upgrade

Error: Unsupported argument
  An argument named "skip_provider_registration" is not expected here.

The provider's major version removed or renamed it. Read the upgrade guide (azurerm 4.0: resource_provider_registrations = "none" replaces skip_provider_registration).

Crash

!!!!!!!!!!!!!!!!!!!!!!!!!!! TERRAFORM CRASH !!!!!!!!!!!!!!!!!!!!!!!!!!!!

A crash.log is written in the working directory. Upgrade to the latest patch release first, since many crashes are already fixed. Otherwise, search Terraform's (or the provider's) GitHub issues, and report it with the log after redacting secrets.

Getting unstuck

  • terraform console to test expressions against real state
  • terraform graph -format=mermaid (1.16+) to see relationships
  • Provider docs for the resource, especially the import section (ID format) and timeouts
  • The provider's GitHub issues: odds are someone hit it first
  • Start a minimal reproduction in a scratch directory with local state