The "Timeout while waiting for state" error occurs when Terraform cannot detect that a resource has reached its desired state within the configured timeout period. This typically indicates either a slow-running operation, resource constraints in your cloud provider, or network connectivity issues.
Terraform manages resources by monitoring their state as they transition from one status to another. When creating, updating, or deleting resources, Terraform polls the cloud provider's API to check if the resource has reached the desired state (e.g., "running" for an EC2 instance, "available" for a database). The timeout error occurs when Terraform has been polling for the configured duration (default varies by resource, typically 5-30 minutes) without the resource reaching its desired state. This doesn't necessarily mean the operation failed—it may still be in progress, but exceeded Terraform's patience.
Look at the Terraform error message to see which resource and state transition timed out:
Error: timeout while waiting for state to become 'running' (timeout: 5m0s)
on main.tf line 12, in resource "aws_instance" "example":
12: resource "aws_instance" "example" {This tells you exactly what to investigate in your cloud provider's console.
Log into your cloud provider (AWS, GCP, Azure, etc.) and verify the resource status:
AWS: Check EC2 dashboard for instance status, RDS for database status
GCP: Check Compute Engine or Cloud SQL dashboards
Azure: Check Virtual Machines or Database blade
Determine if the resource is still provisioning, stuck, or if the operation actually completed.
Add or modify the timeouts block for the resource:
resource "aws_instance" "example" {
ami = "ami-0c55b159cbfafe1f0"
instance_type = "t2.micro"
timeouts {
create = "30m"
delete = "10m"
update = "20m"
}
}
resource "aws_db_instance" "example" {
allocated_storage = 20
engine = "mysql"
timeouts {
create = "60m"
update = "80m"
delete = "40m"
}
}Set the timeout based on your resource type—databases and complex resources need longer timeouts.
Run Terraform with debug logging to see what states it's checking:
TF_LOG=DEBUG terraform applyThis shows the actual API calls and state transitions. Look for patterns in what state Terraform is stuck waiting for and how frequently the provider is polling.
Visit your cloud provider's status page:
- AWS: https://status.aws.amazon.com/
- GCP: https://status.cloud.google.com/
- Azure: https://status.azure.com/
- Terraform: https://status.hashicorp.com/
Look for any degradation in the region or service you're using. If there's an outage, wait for it to resolve.
Ensure all dependencies are properly declared:
resource "aws_security_group" "example" {
name = "example"
}
resource "aws_instance" "example" {
ami = "ami-0c55b159cbfafe1f0"
instance_type = "t2.micro"
vpc_security_group_ids = [aws_security_group.example.id] # Explicit dependency
}Without proper dependencies, resources may be created out of order, causing the instance to wait for the security group.
Verify you haven't hit service limits:
# AWS - Check service quotas
aws service-quotas list-service-quotas --service-code ec2 --region us-east-1
# Check current usage
aws ec2 describe-account-attributes --region us-east-1Common limits:
- EC2 instances per region (default 20)
- Database instances per account (default 40)
- Load balancers per region (default 20)
Request quota increases if needed.
When Terraform times out on instance creation, it often means the AZ has no capacity for that instance type:
# AWS - Check available capacity
aws ec2 describe-spot-price-history \
--instance-types t2.micro \
--region us-east-1 \
--start-time $(date -u +%Y-%m-%dT%H:%M:%S) \
--product-descriptions "Linux/UNIX"Try using a different instance type or availability zone:
resource "aws_instance" "example" {
ami = "ami-0c55b159cbfafe1f0"
instance_type = "t2.small" # Try different type
availability_zone = "us-east-1b" # Try different AZ
}After investigating and fixing the root cause, retry:
# First, check Terraform's state
terraform state list
terraform state show aws_instance.example
# If the resource exists but is still provisioning, just retry apply
terraform apply
# If you need to force recreation
terraform taint aws_instance.example
terraform applyProvider-Specific Timeouts:
- AWS: Database creation can take 5-15 minutes. RDS Multi-AZ adds significant time.
- GCP: Firewall rules propagation can take 1-2 minutes. VM creation is usually fast.
- Azure: Resource group deployment timeouts are independent of individual resource timeouts.
- Terraform Cloud/Enterprise: Applies run in remote environments; network latency increases timeout risk.
For Large Batch Operations:
When provisioning 30+ instances simultaneously, cloud providers often rate-limit or throttle. Solutions:
1. Use count or for_each with increased timeouts
2. Batch operations in waves (create 10, wait, create next 10)
3. Use Terraform's -parallelism=n flag to reduce concurrent requests
Auto-Scaling Timeouts:
When using auto-scaling groups, set proper health check grace periods:
resource "aws_autoscaling_group" "example" {
health_check_grace_period = 300 # Give instances 5 minutes to start
health_check_type = "ELB"
}State Lock Considerations:
If Terraform times out, it may not properly release the state lock. Use terraform force-unlock with caution if needed.
Error: Error rendering template: template not found
How to fix "template not found" error in Terraform
Error: Error generating private key
How to fix 'Error generating private key' in Terraform
Error creating Kubernetes Service: field is immutable
How to fix "field is immutable" errors in Terraform
Error: Error creating local file: open: permission denied
How to fix "Error creating local file: permission denied" in Terraform
Error: line endings have changed from CRLF to LF
Line endings have changed from CRLF to LF in Terraform