1# Cron Triggers Gotchas
2 
3## Common Errors
4 
5### "Timezone Issues"
6 
7**Problem:** Cron runs at wrong time relative to local timezone  
8**Cause:** All crons execute in UTC, no local timezone support  
9**Solution:** Convert local time to UTC manually
10 
11**Conversion formula:** `utcHour = (localHour - utcOffset + 24) % 24`
12 
13**Examples:**
14- 9am PST (UTC-8) → `(9 - (-8) + 24) % 24 = 17` → `0 17 * * *`
15- 2am EST (UTC-5) → `(2 - (-5) + 24) % 24 = 7` → `0 7 * * *`
16- 6pm JST (UTC+9) → `(18 - 9 + 24) % 24 = 33 % 24 = 9` → `0 9 * * *`
17 
18**Daylight Saving Time:** Adjust manually when DST changes, or schedule at times unaffected by DST (e.g., 2am-4am local time usually safe)
19 
20### "Cron Not Executing"
21 
22**Cause:** Missing `scheduled()` export, invalid syntax, propagation delay (<15min), or plan limits  
23**Solution:** Verify export exists, validate at crontab.guru, wait 15+ min after deploy, check plan limits
24 
25### "Duplicate Executions"
26 
27**Cause:** At-least-once delivery  
28**Solution:** Track execution IDs in KV - see idempotency pattern below
29 
30### "Execution Failures"
31 
32**Cause:** CPU exceeded, unhandled exceptions, network timeouts, binding errors  
33**Solution:** Use try-catch, AbortController timeouts, `ctx.waitUntil()` for long ops, or Workflows for heavy tasks
34 
35### "Local Testing Not Working"
36 
37**Problem:** `/__scheduled` endpoint returns 404 or doesn't trigger handler  
38**Cause:** Missing `scheduled()` export, wrangler not running, or incorrect endpoint format  
39**Solution:**
40 
411. Verify `scheduled()` is exported:
42```typescript
43export default {
44  async scheduled(controller, env, ctx) {
45    console.log("Cron triggered");
46  },
47};
48```
49 
502. Start dev server:
51```bash
52npx wrangler dev
53```
54 
553. Use correct endpoint format (URL-encode spaces as `+`):
56```bash
57# Correct
58curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
59 
60# Wrong (will fail)
61curl "http://localhost:8787/__scheduled?cron=*/5 * * * *"
62```
63 
644. Update Wrangler if outdated:
65```bash
66npm install -g wrangler@latest
67```
68 
69### "waitUntil() Tasks Not Completing"
70 
71**Problem:** Background tasks in `ctx.waitUntil()` fail silently or don't execute  
72**Cause:** Promises rejected without error handling, or handler returns before promise settles  
73**Solution:** Always await or handle errors in waitUntil promises:
74 
75```typescript
76export default {
77  async scheduled(controller, env, ctx) {
78    // BAD: Silent failures
79    ctx.waitUntil(riskyOperation());
80    
81    // GOOD: Explicit error handling
82    ctx.waitUntil(
83      riskyOperation().catch(err => {
84        console.error("Background task failed:", err);
85        return logError(err, env);
86      })
87    );
88  },
89};
90```
91 
92### "Idempotency Issues"
93 
94**Problem:** At-least-once delivery causes duplicate side effects (double charges, duplicate emails)  
95**Cause:** No deduplication mechanism  
96**Solution:** Use KV to track execution IDs:
97 
98```typescript
99export default {
100  async scheduled(controller, env, ctx) {
101    const executionId = `${controller.cron}-${controller.scheduledTime}`;
102    const existing = await env.EXECUTIONS.get(executionId);
103    
104    if (existing) {
105      console.log("Already executed, skipping");
106      controller.noRetry();
107      return;
108    }
109    
110    await env.EXECUTIONS.put(executionId, "1", { expirationTtl: 86400 }); // 24h TTL
111    await performIdempotentOperation(env);
112  },
113};
114```
115 
116### "Security Concerns"
117 
118**Problem:** `__scheduled` endpoint exposed in production allows unauthorized cron triggering  
119**Cause:** Testing endpoint available in deployed Workers  
120**Solution:** Block `__scheduled` in production:
121 
122```typescript
123export default {
124  async fetch(request, env, ctx) {
125    const url = new URL(request.url);
126    
127    // Block __scheduled in production
128    if (url.pathname === "/__scheduled" && env.ENVIRONMENT === "production") {
129      return new Response("Not Found", { status: 404 });
130    }
131    
132    return handleRequest(request, env, ctx);
133  },
134  
135  async scheduled(controller, env, ctx) {
136    // Your cron logic
137  },
138};
139```
140 
141**Also:** Use `env.API_KEY` for secrets (never hardcode)
142 
143**Alternative:** Add middleware to verify request origin:
144```typescript
145export default {
146  async fetch(request, env, ctx) {
147    const url = new URL(request.url);
148    
149    if (url.pathname === "/__scheduled") {
150      // Check Cloudflare headers to verify internal request
151      const cfRay = request.headers.get("cf-ray");
152      if (!cfRay && env.ENVIRONMENT === "production") {
153        return new Response("Not Found", { status: 404 });
154      }
155    }
156    
157    return handleRequest(request, env, ctx);
158  },
159  
160  async scheduled(controller, env, ctx) {
161    // Your cron logic
162  },
163};
164```
165 
166## Limits & Quotas
167 
168| Limit | Free | Paid | Notes |
169|-------|------|------|-------|
170| Triggers per Worker | 3 | Unlimited | Maximum cron schedules per Worker |
171| CPU time | 10ms | 30s (<1hr interval), 15min (≥1hr interval) | May need `ctx.waitUntil()` or Workflows |
172| Execution guarantee | At-least-once | At-least-once | Duplicates possible - use idempotency |
173| Propagation delay | Up to 15 minutes | Up to 15 minutes | Time for changes to take effect globally |
174| Min interval | 1 minute | 1 minute | Cannot schedule more frequently |
175| Cron accuracy | ±1 minute | ±1 minute | Execution may drift slightly |
176 
177## Testing Best Practices
178 
179**Unit tests:**
180- Mock `ScheduledController`, `ExecutionContext`, and bindings
181- Test each cron expression separately
182- Verify `noRetry()` is called when expected
183- Use Vitest with `@cloudflare/vitest-pool-workers` for realistic env
184 
185**Integration tests:**
186- Test via `/__scheduled` endpoint in dev environment
187- Verify idempotency logic with duplicate `scheduledTime` values
188- Test error handling and retry behavior
189 
190**Production:** Start with long intervals (`*/30 * * * *`), monitor Cron Events for 24h, set up alerts before reducing interval
191 
192## Resources
193 
194- [Cron Triggers Docs](https://developers.cloudflare.com/workers/configuration/cron-triggers/)
195- [Scheduled Handler API](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/)
196- [Cloudflare Workflows](https://developers.cloudflare.com/workflows/)
197- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)
198- [Crontab Guru](https://crontab.guru/) - Validator
199- [Vitest Pool Workers](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples)
200