Skip to content
DevOps AI ToolKit
Newsletter
Terraform Troubleshooting Toolkit

Terraform Troubleshooting Toolkit

Use this Terraform troubleshooting toolkit to diagnose state lock errors, provider and backend problems, plan-time drift and replacements, variable and module failures, and failed applies.

Paste your error and get a triage plan.

Paste a log line, CLI error, stack trace, service failure, or config snippet and get a structured troubleshooting plan. Your snippet is carried straight into the AI Incident Response Assistant with Terraform context prefilled.

Open the Terraform Incident Assistant → Browse Terraform prompts

Do not paste secrets, tokens, private keys, passwords, or customer data. Your snippet stays in your browser until you open the assistant.

Top 25 Terraform Errors and Failure Modes

The production failures engineers hit most — each links to a full cause → fix → prevention guide.

Provider configuration not present

Terraform can't find provider settings for a resource, usually after a module refactor or removed provider block.

Error acquiring the state lock

A stale or concurrent lock blocks your run, most often a DynamoDB LockID left behind by a crashed apply.

Backend configuration changed

Terraform detects the backend block differs from what's cached and refuses to continue until you reinitialize or migrate.

Invalid index

An index or key reference points at an element that doesn't exist in a list or map, breaking evaluation.

Unsupported attribute

You referenced an attribute the resource or object doesn't expose, often a typo or a schema change after an upgrade.

Invalid value for variable

A supplied variable value fails its type constraint or validation block, so Terraform rejects the input.

Missing required argument

A required argument on a resource or module block was left out, so the configuration won't validate.

Cycle detected

Two or more resources depend on each other, creating a dependency loop Terraform can't order.

Resource already exists

The provider found an existing object where Terraform expected to create one, requiring an import instead.

Drift detected

Real infrastructure no longer matches state because something changed outside Terraform, surfacing as unexpected plan changes.

Plan wants to replace resource

A change to an immutable attribute forces a destroy-and-recreate instead of an in-place update.

Provider authentication failed

The provider couldn't authenticate to the cloud API, typically expired credentials, wrong profile, or missing environment variables.

Invalid provider version

No provider release matches your version constraints, so Terraform can't query or select a package.

Module not found

Terraform can't locate or install a referenced module, often a missing terraform init or a bad source path.

Variables not loading

A reference points to an input variable Terraform never sees, usually a missing declaration or unloaded tfvars file.

Remote state not found

Terraform failed to load or read the state file from its backend, whether missing, moved, or inaccessible.

Workspace mismatch

You're operating in the wrong workspace, so state isolation breaks and resources land in the wrong environment.

Dependency error

The dependency lock file is inconsistent with your configuration or platform, blocking init until it's reconciled.

Timeout while creating resource

The provider gave up waiting for a resource to reach a ready state before its timeout elapsed.

Import failed

An import couldn't map an existing object into state, usually a wrong ID format or an unsupported resource type.

Count/index mismatch

An invalid count argument or count-based index produced an out-of-range reference during planning.

For_each key error

An invalid for_each argument, unknown key, or unstable set breaks resource addressing across a collection.

Sensitive value output issue

A sensitive value leaks into an output or gets exposed where Terraform expects it marked, causing errors or redaction problems.

Terraform init failed

Initialization couldn't install a required provider, commonly a checksum, network, or version-constraint problem.

Terraform apply failed

The provider produced an inconsistent result after apply, so Terraform aborted with a state-vs-reality mismatch.

Validate your config before you redeploy

Catch the structural mistakes that cause outages — 100% in your browser, nothing uploaded.

Terraform Validator Not sure? Start with the Incident Assistant →

Best Terraform Prompts

Turn symptoms, logs, and config into a structured plan with prompts tuned for Terraform.

Terraform Plan Review Checklist

Plan review

Use this prompt

Terraform State Locking Debug

State lock recovery

Use this prompt

Terraform Cloud Auth Best Practices

Provider authentication

Use this prompt

Terraform Drift Detection

Drift detection

Use this prompt

Terraform Module Review

Module debugging

Use this prompt

Terraform Variable Validation

Variable issues

Use this prompt

Terraform for_each Key Stability

for_each debugging

Use this prompt

Terraform Forced Replacement Cause Triage

Unexpected replacements

Use this prompt

Terraform Error Message Debugging

Cryptic error triage

Use this prompt

Download the Terraform Troubleshooting Runbook Pack

A safe path from a failing plan or apply to a clean change — state locks, drift, provider auth, and module debugging.

  • State lock recovery steps
  • Drift & unexpected-replace triage
  • Provider auth & version checks
  • Backend / remote-state fixes
  • Module & for_each debugging
Download the Terraform Runbook Pack

All Terraform Troubleshooting Guides

Grouped by failure-mode type — each guide covers cause, fix, validation, and prevention.

Authentication & TLS (8)

Terraform Error: '401 Unauthorized' from the Remote/Cloud Backend Terraform Error: S3 Backend 'AccessDenied' Reading or Writing State Failed to get existing workspaces authentication failed Failed to download module Invalid expression Migrating Terraform Secrets to Write-Only Arguments Error refreshing state

Networking (2)

Terraform Error: 'moved' block invalid reference (both endpoints exist) Terraform Error: 'remote-exec provisioner error' timeout waiting for SSH connection

Storage (4)

Terraform Error: HCP Terraform cloud block workspace not found Terraform Error: 'workspace ... does not exist' Selected Workspace Missing state snapshot was created by Terraform vX which is newer than current Auditing Terraform Workspace State Isolation Before It Bites Production

Deployment & Builds (14)

Terraform Error: check block assertion failed during plan/apply Terraform Error: import block config generation failed on plan Terraform Error: 'refresh-only plan cannot be applied' When Applying a Saved Plan Invalid count argument value depends on resource attributes that cannot be determined until apply error configuring Terraform AWS Provider Provider produced inconsistent result after apply Error acquiring the state lock Cycle Inconsistent dependency lock file Invalid for_each argument Provider produced inconsistent final plan Reference to undeclared resource A resource with the ID ... already exists

Runtime (1)

Terraform Error: 'local-exec provisioner error' command exited with a non-zero status

Performance (3)

Terraform Error: S3 Backend 'ResourceNotFoundException' — DynamoDB Lock Table Missing Error locking state: ConditionalCheckFailedException timeout while waiting for state to become available

API errors (1)

# forces replacement

Configuration (35)

Terraform Error: 'Invalid combination of arguments' (ConflictsWith / ExactlyOneOf) Terraform Error: 'Invalid ignore_changes' cannot ignore a required argument Terraform Error: 'Error in function call' from jsondecode (invalid character) Terraform Error: 'reference to undeclared provider' Aliased Provider Not Configured Terraform Error: 'Invalid version constraint' Malformed required_version String Terraform Error: 'Error in function call' from yamldecode (invalid YAML on line N) Terraform Error: Call to unknown function for a provider-defined function Terraform Error: 'removed' block still declared in configuration Terraform Error: 'Call to function templatefile failed' invalid template syntax Using mock_provider with configuration_aliases in Terraform Tests Conflicting configuration arguments Duplicate variable declaration Invalid default value for variable Missing newline after argument Reference to undeclared module Variables not allowed Argument or block definition required Call to unknown function Invalid resource type Unsupported Terraform Core version Invalid value for variable Missing required argument Duplicate resource configuration Invalid template interpolation value Provider configuration not present Reference to undeclared input variable Unsupported attribute Unsupported block type Backend configuration changed Invalid function argument Invalid index Module not installed No value for required variable Unsupported argument Passing Aliased Providers Into Terraform Modules the Right Way

Other (22)

Terraform vs OpenTofu: Which Should You Choose in 2026? Terraform Error: 'Duplicate object key' in a for expression collision Terraform Error: 'Error in function call' from cidrsubnet / cidrhost (prefix beyond 32 bits) Terraform Error: 'Output refers to sensitive values' Missing sensitive = true Terraform Error: 'Instance cannot be destroyed' Due to lifecycle prevent_destroy Terraform Error: 'no available provider ... matches constraints' Version Conflict How to Use mock_provider in Terraform Tests (.tftest.hcl) mock_provider vs override_resource vs override_data in Terraform Tests Mocking terraform_remote_state in Terraform Tests (.tftest.hcl) Terraform Tests: Mock Data Sources with mock_provider and override_data Passing mock_provider Through the providers Block in Terraform Tests Backend initialization required, please run state data in S3 does not have the expected content Cannot import non-existent remote object Failed to install provider Failed to load state Failed to query available provider packages Terraform Check Blocks With Scoped Data Sources for Live Health Assertions for_each Set vs Map Keys in Terraform: Stop the Churn Forgetting Terraform Resources With the removed Block (Without Destroying Them) Ordering run Blocks in Terraform Native Tests for Fast, Reliable Suites Rotating OpenTofu State Encryption Keys Without Locking Yourself Out
Browse the full Terraform category

Terraform troubleshooting FAQ

How do I fix 'Error acquiring the state lock'?
Confirm no other apply is actually running, then release the stale lock. For an S3/DynamoDB backend, delete the leftover LockID item (or run terraform force-unlock with the reported lock ID). Only force-unlock when you're certain no concurrent run holds it, since two simultaneous applies can corrupt state.
Why does Terraform say 'Provider configuration not present'?
Terraform can't find a provider block for a resource in state, usually because you removed or renamed a provider, moved resources into a module, or destroyed after deleting the provider config. Re-add the matching provider (including any alias) so Terraform can reach the resources long enough to reconcile or destroy them.
How do I resolve Terraform drift?
Run terraform plan or terraform apply -refresh-only to see how real infrastructure diverged from state. Decide per change whether to reapply your config to restore the intended state, update the code to match reality, or import the object. Add continuous drift detection in CI so out-of-band changes surface before they cause a surprise apply.
Why does my plan want to replace a resource?
You changed an attribute the provider treats as immutable (a 'forces replacement' argument), so Terraform must destroy and recreate the object. Read the plan's '# forces replacement' annotations, and if downtime is unacceptable use create_before_destroy, a moved block, or refactor the change so the update stays in place.
When should I use the Terraform Validator?
Use the Terraform Validator when you want a fast, browser-based syntax and structure check of HCL before you run plan or open a pull request. It catches formatting and obvious configuration mistakes client-side, so it's ideal for quick sanity checks, sharing snippets, or teaching without spinning up a full Terraform environment.
How do I fix 'Invalid for_each argument' or 'Invalid count argument'?
These appear when the count or for_each value depends on data that isn't known until apply, or when a for_each key isn't a stable, unique string. Drive for_each from static keys (like map keys) rather than computed attributes, guard count with known values, and use terraform plan -target or -refresh-only to make the dependency known before the collection is evaluated.