1# Gotchas & Troubleshooting
2 
3## Critical Pitfalls
4 
5### Stream Consumption (MOST COMMON)
6 
7**Problem:** "stream already consumed" or worker hangs
8 
9**Cause:** `message.raw` is `ReadableStream` - consume once only
10 
11**Solution:**
12```typescript
13// ❌ WRONG
14const email1 = await parser.parse(await message.raw.arrayBuffer());
15const email2 = await parser.parse(await message.raw.arrayBuffer()); // FAILS
16 
17// ✅ CORRECT
18const raw = await message.raw.arrayBuffer();
19const email = await parser.parse(raw);
20```
21 
22Consume `message.raw` immediately before any async operations.
23 
24### Destination Verification
25 
26**Problem:** Emails not forwarding
27 
28**Cause:** Destination unverified
29 
30**Solution:** Add destination, check inbox for verification email, click link. Verify status: `GET /zones/{id}/email/routing/addresses`
31 
32### Mail Authentication
33 
34**Problem:** Legitimate emails rejected
35 
36**Cause:** Missing SPF/DKIM/DMARC on sender domain
37 
38**Solution:** Configure sender DNS:
39```dns
40example.com. IN TXT "v=spf1 include:_spf.example.com ~all"
41selector._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=..."
42_dmarc.example.com. IN TXT "v=DMARC1; p=quarantine"
43```
44 
45### Envelope vs Header
46 
47**Problem:** Filtering on wrong address
48 
49**Solution:**
50```typescript
51// Routing/auth: envelope
52if (message.from === "[email protected]") { }
53 
54// Display: headers
55const display = message.headers.get("from");
56```
57 
58### SendEmail Limits
59 
60| Issue | Limit | Solution |
61|-------|-------|----------|
62| From domain | Must own | Use Email Routing domain |
63| Volume | ~100/min Free | Upgrade or throttle |
64| Attachments | Not supported | Link to R2 |
65| Type | Transactional | No bulk |
66 
67## Common Errors
68 
69### CPU Time Exceeded
70 
71**Cause:** Heavy parsing, large emails
72 
73**Solution:**
74```typescript
75const size = parseInt(message.headers.get("content-length") || "0") / 1024 / 1024;
76if (size > 20) {
77  message.setReject("Too large");
78  return;
79}
80 
81ctx.waitUntil(expensiveWork());
82await message.forward("[email protected]");
83```
84 
85### Rule Not Triggering
86 
87**Causes:** Priority conflict, matcher error, catch-all override
88 
89**Solution:** Check priority (lower=first), verify exact match, confirm destination verified
90 
91### Undefined Property
92 
93**Cause:** Missing header
94 
95**Solution:**
96```typescript
97// ❌ WRONG
98const subj = message.headers.get("subject").toLowerCase();
99 
100// ✅ CORRECT
101const subj = message.headers.get("subject")?.toLowerCase() || "";
102```
103 
104## Limits
105 
106| Resource | Free | Paid |
107|----------|------|------|
108| Email size | 25 MB | 25 MB |
109| Rules | 200 | 200 |
110| Destinations | 200 | 200 |
111| CPU time | 10ms | 30s (default), 5min (max) |
112| SendEmail | ~100/min | Higher |
113 
114## Debugging
115 
116### Local
117 
118```bash
119npx wrangler dev
120 
121curl -X POST 'http://localhost:8787/__email' \
122  --header 'content-type: message/rfc822' \
123  --data 'From: [email protected]
124To: [email protected]
125Subject: Test
126 
127Body'
128```
129 
130### Production
131 
132```bash
133npx wrangler tail
134```
135 
136### Pattern
137 
138```typescript
139export default {
140  async email(message, env, ctx) {
141    try {
142      console.log("From:", message.from);
143      await process(message, env);
144    } catch (err) {
145      console.error(err);
146      message.setReject(err.message);
147    }
148  }
149} satisfies ExportedHandler;
150```
151 
152## Auth Troubleshooting
153 
154### Check Status
155 
156```typescript
157const auth = message.headers.get("authentication-results") || "";
158console.log({
159  spf: auth.includes("spf=pass"),
160  dkim: auth.includes("dkim=pass"),
161  dmarc: auth.includes("dmarc=pass")
162});
163 
164if (!auth.includes("pass")) {
165  message.setReject("Failed auth");
166  return;
167}
168```
169 
170### SPF Issues
171 
172**Causes:** Forwarding breaks SPF, too many lookups (>10), missing includes
173 
174**Solution:**
175```dns
176; ✅ Good
177example.com. IN TXT "v=spf1 include:_spf.google.com ~all"
178 
179; ❌ Bad - too many
180example.com. IN TXT "v=spf1 include:a.com include:b.com ... ~all"
181```
182 
183### DMARC Alignment
184 
185**Cause:** From domain must match SPF/DKIM domain
186 
187## Best Practices
188 
1891. Consume `message.raw` immediately
1902. Verify destinations
1913. Handle missing headers (`?.`)
1924. Use envelope for routing
1935. Check spam scores
1946. Test locally first
1957. Use `ctx.waitUntil` for background work
1968. Size-check early
197