1# Pipelines Gotchas
2 
3## Critical Issues
4 
5### Events Silently Dropped
6 
7**Most common issue.** Events accepted (HTTP 200) but never appear in sink.
8 
9**Causes:**
101. Schema validation fails - structured streams drop invalid events silently
112. Waiting for roll interval (10-300s) - expected behavior
12 
13**Solution:** Validate client-side with Zod:
14```typescript
15const EventSchema = z.object({ user_id: z.string(), amount: z.number() });
16try {
17  const validated = EventSchema.parse(rawEvent);
18  await env.STREAM.send([validated]);
19} catch (e) { /* get immediate feedback */ }
20```
21 
22### Pipelines Are Immutable
23 
24Cannot modify SQL after creation. Must delete and recreate.
25 
26```bash
27npx wrangler pipelines delete old-pipeline
28npx wrangler pipelines create new-pipeline --sql "..."
29```
30 
31**Tip:** Use version naming (`events-pipeline-v1`) and keep SQL in version control.
32 
33### Worker Binding Not Found
34 
35**`env.STREAM is undefined`**
36 
371. Use **stream ID** (not pipeline ID) in `wrangler.jsonc`
382. Redeploy after adding binding
39 
40```bash
41npx wrangler pipelines streams list  # Get stream ID
42npx wrangler deploy
43```
44 
45## Common Errors
46 
47| Error | Cause | Fix |
48|-------|-------|-----|
49| Events not in R2 | Roll interval not elapsed | Wait 10-300s, check `roll_interval` |
50| Schema validation failures | Type mismatch, missing fields | Validate client-side |
51| Rate limit (429) | >5 MB/s per stream | Batch events, request increase |
52| Payload too large (413) | >1 MB request | Split into smaller batches |
53| Cannot delete stream | Pipeline references it | Delete pipelines first |
54| Sink credential errors | Token expired | Recreate sink with new credentials |
55 
56## Limits (Open Beta)
57 
58| Resource | Limit |
59|----------|-------|
60| Streams/Sinks/Pipelines per account | 20 each |
61| Payload size | 1 MB |
62| Ingest rate per stream | 5 MB/s |
63| Event retention | 24 hours |
64| Recommended batch size | 100 events |
65 
66## SQL Limitations
67 
68- **No JOINs** - single stream per pipeline
69- **No window functions** - basic SQL only
70- **No subqueries** - must use `INSERT INTO ... SELECT ... FROM`
71- **No schema evolution** - cannot modify after creation
72 
73## Debug Checklist
74 
75- [ ] Stream exists: `npx wrangler pipelines streams list`
76- [ ] Pipeline healthy: `npx wrangler pipelines get <ID>`
77- [ ] SQL syntax matches schema
78- [ ] Worker redeployed after binding added
79- [ ] Waited for roll interval
80- [ ] Accepted vs processed count matches (no validation drops)
81