1# Terraform Troubleshooting & Best Practices
2 
3Common issues, security considerations, and best practices.
4 
5## State Drift Issues
6 
7Some resources have known state drift. Add lifecycle blocks to prevent perpetual diffs:
8 
9| Resource | Drift Attributes | Workaround |
10|----------|------------------|------------|
11| `cloudflare_pages_project` | `deployment_configs.*` | `ignore_changes = [deployment_configs]` |
12| `cloudflare_workers_script` | secrets returned as REDACTED | `ignore_changes = [secret_text_binding]` |
13| `cloudflare_load_balancer` | `adaptive_routing`, `random_steering` | `ignore_changes = [adaptive_routing, random_steering]` |
14| `cloudflare_workers_kv` | special chars in keys (< 5.16.0) | Upgrade to 5.16.0+ |
15 
16```hcl
17# Example: Ignore secret drift
18resource "cloudflare_workers_script" "api" {
19  account_id = var.account_id
20  name = "api-worker"
21  content = file("worker.js")
22  secret_text_binding { name = "API_KEY"; text = var.api_key }
23  
24  lifecycle {
25    ignore_changes = [secret_text_binding]
26  }
27}
28```
29 
30## v5 Breaking Changes
31 
32Provider v5 is current (auto-generated from OpenAPI). v4→v5 has breaking changes:
33 
34**Resource Renames:**
35 
36| v4 Resource | v5 Resource | Notes |
37|-------------|-------------|-------|
38| `cloudflare_record` | `cloudflare_dns_record` | |
39| `cloudflare_worker_script` | `cloudflare_workers_script` | Note: plural |
40| `cloudflare_worker_*` | `cloudflare_workers_*` | All worker resources |
41| `cloudflare_access_*` | `cloudflare_zero_trust_*` | Access → Zero Trust |
42 
43**Attribute Changes:**
44 
45| v4 Attribute | v5 Attribute | Resources |
46|--------------|--------------|-----------|
47| `zone` | `name` | zone |
48| `account_id` | `account.id` | zone (object syntax) |
49| `key` | `key_name` | KV |
50| `location_hint` | `location` | R2 |
51 
52**State Migration:**
53 
54```bash
55# Rename resources in state after v5 upgrade
56terraform state mv cloudflare_record.example cloudflare_dns_record.example
57terraform state mv cloudflare_worker_script.api cloudflare_workers_script.api
58```
59 
60## Resource-Specific Gotchas
61 
62### R2 Location Case Sensitivity
63 
64**Problem:** Terraform creates R2 bucket but fails on subsequent applies  
65**Cause:** Location must be UPPERCASE  
66**Solution:** Use `WNAM`, `ENAM`, `WEUR`, `EEUR`, `APAC` (not `wnam`, `enam`, etc.)
67 
68```hcl
69resource "cloudflare_r2_bucket" "assets" {
70  account_id = var.account_id
71  name = "assets"
72  location = "WNAM"  # UPPERCASE required
73}
74```
75 
76### KV Special Characters (< 5.16.0)
77 
78**Problem:** Keys with `+`, `#`, `%` cause encoding issues  
79**Cause:** URL encoding bug in provider < 5.16.0  
80**Solution:** Upgrade to 5.16.0+ or avoid special chars in keys
81 
82### D1 Migrations
83 
84**Problem:** Terraform creates database but schema is empty  
85**Cause:** Terraform only creates D1 resource, not schema  
86**Solution:** Run migrations via wrangler after Terraform apply
87 
88```bash
89# After terraform apply
90wrangler d1 migrations apply <db-name>
91```
92 
93### Worker Script Size Limit
94 
95**Problem:** Worker deployment fails with "script too large"  
96**Cause:** Worker script + dependencies exceed 10 MB limit  
97**Solution:** Use code splitting, external dependencies, or minification
98 
99### Pages Project Drift
100 
101**Problem:** Pages project shows perpetual diff on `deployment_configs`  
102**Cause:** Cloudflare API adds default values not in Terraform state  
103**Solution:** Add lifecycle ignore block (see State Drift table above)
104 
105## Common Errors
106 
107### "Error: couldn't find resource"
108 
109**Cause:** Resource was deleted outside Terraform  
110**Solution:** Import resource back into state with `terraform import cloudflare_zone.example <zone-id>` or remove from state with `terraform state rm cloudflare_zone.example`
111 
112### "409 Conflict on worker deployment"
113 
114**Cause:** Worker being deployed by both Terraform and wrangler simultaneously  
115**Solution:** Choose one deployment method; if using Terraform, remove wrangler deployments
116 
117### "DNS record already exists"
118 
119**Cause:** Existing DNS record not imported into Terraform state  
120**Solution:** Find record ID in Cloudflare dashboard and import with `terraform import cloudflare_dns_record.example <zone-id>/<record-id>`
121 
122### "Invalid provider configuration"
123 
124**Cause:** API token missing, invalid, or lacking required permissions  
125**Solution:** Set `CLOUDFLARE_API_TOKEN` environment variable or check token permissions in dashboard
126 
127### "State locking errors"
128 
129**Cause:** Multiple concurrent Terraform runs or stale lock from crashed process  
130**Solution:** Remove stale lock with `terraform force-unlock <lock-id>` (use with caution)
131 
132## Limits
133 
134| Resource | Limit | Notes |
135|----------|-------|-------|
136| API token rate limit | Varies by plan | Use `api_client_logging = true` to debug
137| Worker script size | 10 MB | Includes all dependencies
138| KV keys per namespace | Unlimited | Pay per operation
139| R2 storage | Unlimited | Pay per GB
140| D1 databases | 50,000 per account | Free tier: 10
141| Pages projects | 500 per account | 100 for free accounts
142| DNS records | 3,500 per zone | Free plan
143 
144## See Also
145 
146- [README](./README.md) - Provider setup
147- [Configuration](./configuration.md) - Resources
148- [API](./api.md) - Data sources
149- [Patterns](./patterns.md) - Use cases
150- Provider docs: https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs
151