1# Tail Workers Gotchas & Debugging
2 
3## Critical Pitfalls
4 
5### 1. Not Using `ctx.waitUntil()`
6 
7**Problem:** Async work doesn't complete or tail Worker times out  
8**Cause:** Handlers exit immediately; awaiting blocks processing  
9**Solution:**
10 
11```typescript
12// ❌ WRONG - fire and forget
13export default {
14  async tail(events) {
15    fetch(endpoint, { body: JSON.stringify(events) });
16  }
17};
18 
19// ❌ WRONG - blocking await
20export default {
21  async tail(events, env, ctx) {
22    await fetch(endpoint, { body: JSON.stringify(events) });
23  }
24};
25 
26// ✅ CORRECT
27export default {
28  async tail(events, env, ctx) {
29    ctx.waitUntil(
30      (async () => {
31        await fetch(endpoint, { body: JSON.stringify(events) });
32        await processMore();
33      })()
34    );
35  }
36};
37```
38 
39### 2. Missing `tail()` Handler
40 
41**Problem:** Producer deployment fails  
42**Cause:** Worker in `tail_consumers` doesn't export `tail()` handler  
43**Solution:** Ensure `export default { async tail(events, env, ctx) { ... } }`
44 
45### 3. Outcome vs HTTP Status
46 
47**Problem:** Filtering by wrong status  
48**Cause:** `outcome` is script execution status, not HTTP status
49 
50```typescript
51// ❌ WRONG
52if (event.outcome === 500) { /* never matches */ }
53 
54// ✅ CORRECT
55if (event.outcome === 'exception') { /* script threw */ }
56if (event.event?.response?.status === 500) { /* HTTP 500 */ }
57```
58 
59### 4. Timestamp Units
60 
61**Problem:** Dates off by 1000x  
62**Cause:** Timestamps are epoch milliseconds, not seconds
63 
64```typescript
65// ❌ WRONG: const date = new Date(event.eventTimestamp * 1000);
66// ✅ CORRECT: const date = new Date(event.eventTimestamp);
67```
68 
69### 5. Type Name Mismatch
70 
71**Problem:** Using `TailItem` type  
72**Cause:** Old docs used `TailItem`, SDK uses `TraceItem`
73 
74```typescript
75import type { TraceItem } from '@cloudflare/workers-types';
76export default {
77  async tail(events: TraceItem[], env, ctx) { /* ... */ }
78};
79```
80 
81### 6. Excessive Logging Volume
82 
83**Problem:** Unexpected high costs  
84**Cause:** Invoked on EVERY producer request  
85**Solution:** Sample events
86 
87```typescript
88export default {
89  async tail(events, env, ctx) {
90    if (Math.random() > 0.1) return;  // 10% sample
91    ctx.waitUntil(sendToEndpoint(events));
92  }
93};
94```
95 
96### 7. Serialization Issues
97 
98**Problem:** `JSON.stringify()` fails  
99**Cause:** `log.message` is `unknown[]` with non-serializable values  
100**Solution:**
101 
102```typescript
103const safePayload = events.map(e => ({
104  ...e,
105  logs: e.logs.map(log => ({
106    ...log,
107    message: log.message.map(m => {
108      try { return JSON.parse(JSON.stringify(m)); }
109      catch { return String(m); }
110    })
111  }))
112}));
113```
114 
115### 8. Missing Error Handling
116 
117**Problem:** Tail Worker silently fails  
118**Cause:** No try/catch  
119**Solution:**
120 
121```typescript
122ctx.waitUntil((async () => {
123  try {
124    await fetch(env.ENDPOINT, { body: JSON.stringify(events) });
125  } catch (error) {
126    console.error("Tail error:", error);
127    await env.FALLBACK_KV.put(`failed:${Date.now()}`, JSON.stringify(events));
128  }
129})());
130```
131 
132### 9. Deployment Order
133 
134**Problem:** Producer deployment fails  
135**Cause:** Tail consumer not deployed yet  
136**Solution:** Deploy tail consumer FIRST
137 
138```bash
139cd tail-worker && wrangler deploy
140cd ../producer && wrangler deploy
141```
142 
143### 10. No Event Retry
144 
145**Problem:** Events lost when handler fails  
146**Cause:** Failed invocations NOT retried  
147**Solution:** Implement fallback storage (see #8)
148 
149## Debugging
150 
151**View logs:** `wrangler tail my-tail-worker`
152 
153**Incremental testing:**
1541. Verify receipt: `console.log('Events:', events.length)`
1552. Inspect structure: `console.log(JSON.stringify(events[0], null, 2))`
1563. Add external call with `ctx.waitUntil()`
157 
158**Monitor dashboard:** Check invocation count (matches producer?), error rate, CPU time
159 
160## Testing
161 
162Add test endpoint to producer:
163 
164```typescript
165export default {
166  async fetch(request) {
167    if (request.url.includes('/test')) {
168      console.log('Test log');
169      throw new Error('Test error');
170    }
171    return new Response('OK');
172  }
173};
174```
175 
176Trigger: `curl https://producer.example.workers.dev/test`
177 
178## Common Errors
179 
180| Error | Cause | Solution |
181|-------|-------|----------|
182| "Tail consumer not found" | Not deployed | Deploy tail Worker first |
183| "No tail handler" | Missing `tail()` | Add to default export |
184| "waitUntil is not a function" | Missing `ctx` | Add `ctx` parameter |
185| Timeout | Blocking await | Use `ctx.waitUntil()` |
186 
187## Performance Notes
188 
189- Max 100 events per invocation
190- Each consumer receives all events independently
191- CPU limits same as regular Workers
192- For high volume, use Durable Objects batching
193