How to debug Terraform errors

Terraform errors fall into distinct categories that require different debugging approaches: configuration errors caught before any API call, provider errors from the OpenStack API, and state management issues. This guide covers the debugging workflow, common error patterns, and recovery procedures.

Debug output#

Enable verbose logging to see the full HTTP request/response cycle between Terraform and the OpenStack API.

Set the log level#

export TF_LOG=DEBUG
terraform apply

Write logs to a file#

export TF_LOG=DEBUG
export TF_LOG_PATH=./terraform-debug.log
terraform apply

Review the log for the HTTP status code and response body from the OpenStack API. Search for HTTP/1.1 4 or HTTP/1.1 5 to find error responses.

Disable logging#

unset TF_LOG
unset TF_LOG_PATH

Debugging workflow#

Follow this sequence when a Terraform operation fails.

1. Format and validate#

Catch syntax and configuration errors before they reach the API:

terraform fmt -check -recursive
terraform validate

validate checks HCL syntax, required attributes, and type constraints. It does not contact the OpenStack API.

2. Plan#

terraform plan -out=tfplan

Review the plan output for unexpected resource changes. If the plan itself fails, the error is an authentication failure (Authentication failed or Could not find Application Credential) or a provider-configuration failure (No suitable endpoint could be found in the service catalog).

3. Apply with targeted debugging#

If apply fails on a specific resource, isolate it:

terraform apply -target=openstack_compute_instance_v2.web

Enable debug logging for the isolated apply to capture the exact API interaction.

4. Inspect state#

After a partial failure, check what Terraform recorded:

terraform state list
terraform state show openstack_compute_instance_v2.web

Common OpenStack provider errors#

State lock recovery#

Terraform uses a lock to prevent concurrent modifications. If a Terraform process crashes or is interrupted, the lock may remain.

Symptoms#

Error: Error acquiring the state lock
Lock Info:
  ID:        12345678-abcd-...
  Path:      terraform.tfstate
  Operation: OperationTypeApply
  Who:       user@hostname
  Created:   2026-04-08 12:00:00 +0000 UTC

Resolution#

1. Verify no other Terraform process is running against the same state.
2. Force-unlock using the lock ID from the error message:

terraform force-unlock 12345678-abcd-...

Plan/apply drift#

Drift occurs when resources are modified outside Terraform (via the console, CLI, or another automation tool).

Detecting drift#

terraform plan

If the plan shows changes you did not make in your .tf files, resources have drifted. Terraform will report either an update-in-place or a forced replacement.

Resolving drift#

Option 1: Accept the external changes. Refresh state to match reality:

terraform apply -refresh-only

Review the changes and approve. This updates Terraform's state without modifying infrastructure.

Option 2: Revert to Terraform's definition. Run a normal apply to push the .tf configuration back to the infrastructure:

terraform apply

Import errors#

When importing existing resources into Terraform state:

terraform import openstack_compute_instance_v2.web INSTANCE_ID

Common import failures#

Provider-level retry configuration#

The OpenStack Terraform provider supports retry configuration for transient failures:

provider "openstack" {
  max_retries = 3
}

This retries on connection errors and 5xx responses. For more granular control over retry behavior, see Retry and resilience patterns.

See also#

• How to deploy infrastructure with Terraform: basic Terraform workflow
• Full-stack Terraform deployment: multi-resource deployment
• Terraform state management: remote state and locking
• Automation API error reference: Heat API status codes and stack state machine
• Error response format: parsing OpenStack JSON errors
• Auth token diagnostics: credential and token debugging
• Retry and resilience patterns: backoff algorithms and retry guidance