1# Troubleshooting & Best Practices
2 
3## Common Errors
4 
5### "No bundler/build step" - Pulumi uploads raw code
6 
7**Problem:** Worker fails with "Cannot use import statement outside a module"  
8**Cause:** Pulumi doesn't bundle Worker code - uploads exactly what you provide  
9**Solution:** Build Worker BEFORE Pulumi deploy
10 
11```typescript
12// WRONG: Pulumi won't bundle this
13const worker = new cloudflare.WorkerScript("worker", {
14    content: fs.readFileSync("./src/index.ts", "utf8"), // Raw TS file
15});
16 
17// RIGHT: Build first, then deploy
18import * as command from "@pulumi/command";
19const build = new command.local.Command("build", {
20    create: "npm run build",
21    dir: "./worker",
22});
23const worker = new cloudflare.WorkerScript("worker", {
24    content: build.stdout.apply(() => fs.readFileSync("./worker/dist/index.js", "utf8")),
25}, {dependsOn: [build]});
26```
27 
28### "wrangler.toml not consumed" - Config drift
29 
30**Problem:** Local wrangler dev works, Pulumi deploy fails  
31**Cause:** Pulumi ignores wrangler.toml - must duplicate config  
32**Solution:** Generate wrangler.toml from Pulumi or keep synced manually
33 
34```typescript
35// Pattern: Export Pulumi config to wrangler.toml
36const workerConfig = {
37    name: "my-worker",
38    compatibilityDate: "2025-01-01",
39    compatibilityFlags: ["nodejs_compat"],
40};
41 
42new command.local.Command("generate-wrangler", {
43    create: pulumi.interpolate`cat > wrangler.toml <<EOF
44name = "${workerConfig.name}"
45compatibility_date = "${workerConfig.compatibilityDate}"
46compatibility_flags = ${JSON.stringify(workerConfig.compatibilityFlags)}
47EOF`,
48});
49```
50 
51### "False no-changes detection" - Content SHA unchanged
52 
53**Problem:** Worker code updated, Pulumi says "no changes"  
54**Cause:** Content hash identical (whitespace/comment-only change)  
55**Solution:** Add build timestamp or version to force update
56 
57```typescript
58const version = Date.now().toString();
59const worker = new cloudflare.WorkerScript("worker", {
60    content: code,
61    plainTextBindings: [{name: "VERSION", text: version}], // Forces new deployment
62});
63```
64 
65### "D1 migrations don't run on pulumi up"
66 
67**Problem:** Database schema not applied after D1 database created  
68**Cause:** Pulumi creates database but doesn't run migrations  
69**Solution:** Use Command resource with dependsOn
70 
71```typescript
72const db = new cloudflare.D1Database("db", {accountId, name: "mydb"});
73 
74// Run migrations after DB created
75const migration = new command.local.Command("migrate", {
76    create: pulumi.interpolate`wrangler d1 execute ${db.name} --file ./schema.sql`,
77}, {dependsOn: [db]});
78 
79// Worker depends on migrations
80const worker = new cloudflare.WorkerScript("worker", {
81    d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
82}, {dependsOn: [migration]});
83```
84 
85### "Missing required property 'accountId'"
86 
87**Problem:** `Error: Missing required property 'accountId'`  
88**Cause:** Account ID not provided in resource configuration  
89**Solution:** Add to stack config
90 
91```yaml
92# Pulumi.<stack>.yaml
93config:
94  cloudflare:accountId: "abc123..."
95```
96 
97### "Binding name mismatch"
98 
99**Problem:** Worker fails with "env.MY_KV is undefined"  
100**Cause:** Binding name in Pulumi != name in Worker code  
101**Solution:** Match exactly (case-sensitive)
102 
103```typescript
104// Pulumi
105kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}]
106 
107// Worker code
108export default { async fetch(request, env) { await env.MY_KV.get("key"); }}
109```
110 
111### "API token permissions insufficient"
112 
113**Problem:** `Error: authentication error (10000)`  
114**Cause:** Token lacks required permissions  
115**Solution:** Grant token permissions: Account.Workers Scripts:Edit, Account.Account Settings:Read
116 
117### "Resource not found after import"
118 
119**Problem:** Imported resource shows as changed on next `pulumi up`  
120**Cause:** State mismatch between actual resource and Pulumi config  
121**Solution:** Check property names/types match exactly
122 
123```bash
124pulumi import cloudflare:index/workerScript:WorkerScript my-worker <account_id>/<worker_name>
125pulumi preview # If shows changes, adjust Pulumi code to match actual resource
126```
127 
128### "v6.x Worker versioning confusion"
129 
130**Problem:** Worker deployed but not receiving traffic  
131**Cause:** v6.x requires Worker + WorkerVersion + WorkersDeployment (3 resources)  
132**Solution:** Use WorkerScript (auto-versioning) OR full versioning pattern
133 
134```typescript
135// SIMPLE: WorkerScript auto-versions (default behavior)
136const worker = new cloudflare.WorkerScript("worker", {
137    accountId, name: "my-worker", content: code,
138});
139 
140// ADVANCED: Manual versioning for gradual rollouts (v6.x)
141const worker = new cloudflare.Worker("worker", {accountId, name: "my-worker"});
142const version = new cloudflare.WorkerVersion("v1", {
143    accountId, workerId: worker.id, content: code, compatibilityDate: "2025-01-01",
144});
145const deployment = new cloudflare.WorkersDeployment("prod", {
146    accountId, workerId: worker.id, versionId: version.id,
147});
148```
149 
150## Best Practices
151 
1521. **Always set compatibilityDate** - Locks Worker behavior, prevents breaking changes
1532. **Build before deploy** - Pulumi doesn't bundle; use Command resource or CI build step
1543. **Match binding names** - Case-sensitive, must match between Pulumi and Worker code
1554. **Use dependsOn for migrations** - Ensure D1 migrations run before Worker deploys
1565. **Version Worker content** - Add VERSION binding to force redeployment on content changes
1576. **Store secrets in stack config** - Use `pulumi config set --secret` for API keys
158 
159## Limits
160 
161| Resource | Limit | Notes |
162|----------|-------|-------|
163| Worker script size | 10 MB | Includes all dependencies, after compression |
164| Worker CPU time | 10ms (free), 30s default / 5min max (paid) | Per request |
165| KV keys per namespace | Unlimited | 1000 ops/sec write, 100k ops/sec read |
166| R2 storage | Unlimited | Class A ops: 1M/mo free, Class B: 10M/mo free |
167| D1 databases | 50,000 per account | Free: 10 per account, 5 GB each |
168| Queues | 10,000 per account | Free: 1M ops/day |
169| Pages projects | 500 per account | Free: 100 projects |
170| API requests | Varies by plan | ~1200 req/5min on free |
171 
172## Resources
173 
174- **Pulumi Registry:** https://www.pulumi.com/registry/packages/cloudflare/
175- **API Docs:** https://www.pulumi.com/registry/packages/cloudflare/api-docs/
176- **GitHub:** https://github.com/pulumi/pulumi-cloudflare
177- **Cloudflare Docs:** https://developers.cloudflare.com/
178- **Workers Docs:** https://developers.cloudflare.com/workers/
179 
180---
181See: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)
182