Cloud ComputingTerraform Debug: Enable TF_LOG and Troubleshoot
Enable Terraform debug mode with TF_LOG. Save logs to file, interpret output, and fix terraform plan and apply errors fast.
5 min read
DevOps
Terraform Troubleshooting - Common Errors and Solutions
Fix the most common Terraform errors. State lock issues, provider bugs, dependency cycles, plan/apply failures, and authentication problems — all solved.
LLuca Berton4 min read
Quick Reference
#This is a central guide linking to specific error fixes. Use the table below to jump directly to the error you're hitting.
Most Common Errors
#State and Lock Errors
#| Error | Quick Fix | Full Guide |
|---|---|---|
| State lock conflict | Wait for other apply to finish, or terraform force-unlock LOCK_ID | State Lock Guide |
| State snapshot newer version | Upgrade Terraform to match the version that created the state | Version Mismatch |
| Inconsistent dependency lock file | Run terraform init -upgrade | Lock File Fix |
Provider Errors
#| Error | Quick Fix | Full Guide |
|---|---|---|
| Provider configuration not present | Add missing provider block or remove orphaned state entries | Provider Missing |
| Plugin crashed | Clear .terraform/providers, run terraform init | Plugin Crash |
| Provider version conflict | Use version constraints in required_providers | Version Conflict |
Authentication Errors
#| Error | Quick Fix | Full Guide |
|---|---|---|
| AWS InvalidClientTokenId | Check AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY | AWS Auth |
| AssumeRole AccessDenied | Fix trust policy in target account + sts:AssumeRole in source | AssumeRole |
| Azure Authorization Failed | Assign Contributor role to service principal | Azure Auth |
| GCP 403 Forbidden | Enable API, check IAM roles | GCP Perms |
Resource Errors
#| Error | Quick Fix | Full Guide |
|---|---|---|
| Resource already exists | Import with terraform import or rename | Already Exists |
| Cycle detected | Break circular dependency with separate resources | Cycles |
| Timeout waiting for state | Add timeouts block with longer values | Timeouts |
| Invalid AMI ID | Check region, use data source lookup | AMI Not Found |
HCL and Type Errors
#| Error | Quick Fix | Full Guide |
|---|---|---|
| Invalid for_each argument | Use static variables for keys, not computed values | for_each |
| Inconsistent conditional types | Use tostring(), tolist(), or null | Conditionals |
| Invalid template interpolation | Use jsonencode() for complex types in strings | Templates |
| Invalid function argument | Check expected parameter types | Functions |
| Unexpected token | Run terraform fmt, check brackets | Syntax |
AWS "Error creating" Errors by Service
#When terraform apply fails with an Error creating <resource> message, it's usually one of three causes: the resource already exists (import it), an IAM permission is missing, or a parameter is invalid. Find your specific AWS error below.
Compute, containers & serverless
#- EKS cluster — AccessDeniedException
- EKS node group — InvalidParameterException
- ECS service — InvalidParameterException
- ECR repository — RepositoryAlreadyExistsException
- Lambda function — InvalidParameterValueException
- Step Functions — StateMachineAlreadyExists
- Glue job — AlreadyExistsException
Networking
#- Subnet — InvalidSubnet.Conflict
- Route — RouteAlreadyExists
- NAT gateway — NotFound
- VPC peering — PeeringConnectionAlreadyExists
- Security group — InvalidGroup.Duplicate
- ALB listener — CertificateNotFound
- CloudFront — CNAMEAlreadyExists
- Route 53 record — InvalidChangeBatch
- API Gateway — ConflictException
Databases & storage
#- RDS cluster — DBClusterAlreadyExists
- RDS — DBSubnetGroupNotFoundFault
- DynamoDB table — ResourceInUseException
- ElastiCache — CacheClusterAlreadyExists
- Neptune cluster — DBClusterNotFoundFault
- EBS volume — VolumeInUse
- OpenSearch domain — ValidationException
Messaging & streaming
#- SQS queue — QueueAlreadyExists
- SNS topic — AuthorizationError
- Kinesis stream — ResourceInUseException
- MSK cluster — TooManyRequestsException
- EventBridge rule — ResourceAlreadyExistsException
Security, identity & management
#- IAM role — MalformedPolicyDocument
- KMS key — MalformedPolicyDocument
- ACM certificate — LimitExceededException
- Secrets Manager — ResourceExistsException
- Cognito user pool — UsernameExistsException
- WAFv2 WebACL — WAFInvalidParameterException
- CloudWatch log group — ResourceAlreadyExistsException
- CodePipeline — InvalidStructure
- Transfer server — ConflictException
General Debugging Steps
#1. Enable Debug Logging
#export TF_LOG=DEBUG
export TF_LOG_PATH=terraform-debug.log
terraform plan2. Validate Configuration
#terraform validate # Catches syntax and type errors
terraform fmt -check # Catches formatting issues3. Refresh State
#terraform apply -refresh-only # Sync state with reality4. Target Specific Resources
#terraform plan -target=aws_instance.web # Isolate the problem5. Check Provider Version
#terraform version # Shows Terraform + provider versions
terraform init -upgrade # Update to latest compatible versionsCommon Patterns
#"I changed nothing but plan shows changes"
#This is a perpetual diff — usually caused by API normalization. Fix with ignore_changes or jsonencode().
"Apply succeeded but state is wrong"
#terraform apply -refresh-only # Resync state
terraform state show aws_instance.web # Inspect state"Can't destroy — resource has dependencies"
#terraform destroy -target=aws_instance.web # Destroy specific resource firstRelated Articles
#Frequently asked questions
#How do I debug a Terraform error?
#Enable debug logging with export TF_LOG=DEBUG (optionally TF_LOG_PATH=terraform.log) and re-run the command. Then run terraform validate to catch syntax/type errors and terraform fmt -check for formatting. The verbose logs show the exact API call that failed.
Why does Terraform say a resource already exists?
#The resource exists in your cloud account but not in Terraform state — usually because it was created manually or in a previous run. Import it with terraform import <address> <id>, or rename/remove the duplicate. See the AWS "Error creating" section above for service-specific fixes.
How do I fix "Error acquiring the state lock"?
#Another process holds the lock, or a previous run crashed. Wait for the other run to finish, or force-unlock with terraform force-unlock <LOCK_ID> once you confirm no apply is running.
Why does terraform plan show changes when I changed nothing?
#This is a perpetual diff, usually caused by the provider normalizing a value (e.g. JSON policy formatting). Fix it with ignore_changes in a lifecycle block or by wrapping the value in jsonencode().
Conclusion
#Most Terraform errors fall into five categories: state/lock issues, provider problems, authentication failures, resource conflicts, and HCL type errors. This guide links to detailed solutions for each. When in doubt, enable debug logging (TF_LOG=DEBUG), run terraform validate, and check provider versions.
#Terraform#Troubleshooting#Debugging#DevOps#Tips
Related articles
Cloud Computing
DevOpsHow to Install and Use TFLint for Terraform Linting
Install TFLint on macOS, Linux, Windows, or Docker and lint your Terraform code. Covers .tflint.hcl config, AWS/Azure/GCP plugins, and CI/CD integration.
5 min read
TerraformResolve "Inconsistent Dependency Lock File" Error in Terraform
Encountering the Inconsistent Dependency Lock File error in Terraform? This guide explains the causes and provides step-by-step solutions to resolve the.
4 min read
TerraformTerraform Logging: TF_LOG Levels, TF_LOG_PATH, and Debugging
Complete guide to Terraform logging. Set TF_LOG to TRACE, DEBUG, INFO, WARN, or ERROR. Save verbose output to a file with TF_LOG_PATH. Works on Linux, macOS.
2 min read