1# Queues Gotchas & Troubleshooting
2 
3## CRITICAL: Top Production Mistakes
4 
5### 1. "Entire Batch Retried After Single Error"
6 
7**Problem:** Throwing uncaught error in queue handler retries the entire batch, not just the failed message  
8**Cause:** Uncaught exceptions propagate to the runtime, triggering batch-level retry  
9**Solution:** Always wrap individual message processing in try/catch and call `msg.retry()` explicitly
10 
11```typescript
12// ❌ BAD: Throws error, retries entire batch
13async queue(batch: MessageBatch): Promise<void> {
14  for (const msg of batch.messages) {
15    await riskyOperation(msg.body); // If this throws, entire batch retries
16    msg.ack();
17  }
18}
19 
20// ✅ GOOD: Catch per message, handle individually
21async queue(batch: MessageBatch): Promise<void> {
22  for (const msg of batch.messages) {
23    try {
24      await riskyOperation(msg.body);
25      msg.ack();
26    } catch (error) {
27      msg.retry({ delaySeconds: 60 });
28    }
29  }
30}
31```
32 
33### 2. "Messages Retry Forever"
34 
35**Problem:** Messages not explicitly ack'd or retry'd will auto-retry indefinitely  
36**Cause:** Runtime default behavior retries unhandled messages until `max_retries` reached  
37**Solution:** Always call `msg.ack()` or `msg.retry()` for each message. Never leave messages unhandled.
38 
39```typescript
40// ❌ BAD: Skipped messages auto-retry forever
41async queue(batch: MessageBatch): Promise<void> {
42  for (const msg of batch.messages) {
43    if (shouldProcess(msg.body)) {
44      await process(msg.body);
45      msg.ack();
46    }
47    // Missing: msg.ack() for skipped messages - they will retry!
48  }
49}
50 
51// ✅ GOOD: Explicitly handle all messages
52async queue(batch: MessageBatch): Promise<void> {
53  for (const msg of batch.messages) {
54    if (shouldProcess(msg.body)) {
55      await process(msg.body);
56      msg.ack();
57    } else {
58      msg.ack(); // Explicitly ack even if not processing
59    }
60  }
61}
62```
63 
64## Common Errors
65 
66### "Duplicate Message Processing"
67 
68**Problem:** Same message processed multiple times  
69**Cause:** At-least-once delivery guarantee means duplicates are possible during retries  
70**Solution:** Design consumers to be idempotent by tracking processed message IDs in KV with expiration TTL
71 
72```typescript
73async queue(batch: MessageBatch, env: Env): Promise<void> {
74  for (const msg of batch.messages) {
75    const processed = await env.PROCESSED_KV.get(msg.id);
76    if (processed) {
77      msg.ack();
78      continue;
79    }
80    
81    await processMessage(msg.body);
82    await env.PROCESSED_KV.put(msg.id, '1', { expirationTtl: 86400 });
83    msg.ack();
84  }
85}
86```
87 
88### "Pull Consumer Can't Decode Messages"
89 
90**Problem:** Pull consumer or dashboard shows unreadable message bodies  
91**Cause:** Messages sent with `v8` content type are only decodable by Workers push consumers  
92**Solution:** Use `json` content type for pull consumers or dashboard visibility
93 
94```typescript
95// Use json for pull consumers
96await env.MY_QUEUE.send(data, { contentType: 'json' });
97 
98// Use v8 only for push consumers with complex JS types
99await env.MY_QUEUE.send({ date: new Date(), tags: new Set() }, { contentType: 'v8' });
100```
101 
102### "Messages Not Being Delivered"
103 
104**Problem:** Messages sent but consumer not processing  
105**Cause:** Queue paused, consumer not configured, or consumer errors  
106**Solution:** Check queue status with `wrangler queues list`, verify consumer configured with `wrangler queues consumer add`, and check logs with `wrangler tail`
107 
108### "High Dead Letter Queue Rate"
109 
110**Problem:** Many messages ending up in DLQ  
111**Cause:** Consumer repeatedly failing to process messages after max retries  
112**Solution:** Review consumer error logs, check external dependency availability, verify message format matches expectations, or increase retry delay
113 
114## Error Classification Patterns
115 
116Classify errors to decide whether to retry or DLQ:
117 
118```typescript
119async queue(batch: MessageBatch, env: Env): Promise<void> {
120  for (const msg of batch.messages) {
121    try {
122      await processMessage(msg.body);
123      msg.ack();
124    } catch (error) {
125      // Transient errors: retry with backoff
126      if (isRetryable(error)) {
127        const delay = Math.min(30 * (2 ** msg.attempts), 43200);
128        msg.retry({ delaySeconds: delay });
129      } 
130      // Permanent errors: ack to avoid infinite retries
131      else {
132        console.error('Permanent error, sending to DLQ:', error);
133        await env.ERROR_LOG.put(msg.id, JSON.stringify({ msg: msg.body, error: String(error) }));
134        msg.ack(); // Prevent further retries
135      }
136    }
137  }
138}
139 
140function isRetryable(error: unknown): boolean {
141  if (error instanceof Response) {
142    // Retry: rate limits, timeouts, server errors
143    return error.status === 429 || error.status >= 500;
144  }
145  if (error instanceof Error) {
146    // Don't retry: validation, auth, not found
147    return !error.message.includes('validation') && 
148           !error.message.includes('unauthorized') &&
149           !error.message.includes('not found');
150  }
151  return false; // Unknown errors don't retry
152}
153```
154 
155### "CPU Time Exceeded in Consumer"
156 
157**Problem:** Consumer fails with CPU time limit exceeded  
158**Cause:** Consumer processing exceeding 30s default CPU time limit  
159**Solution:** Increase CPU limit in wrangler.jsonc: `{ "limits": { "cpu_ms": 300000 } }` (5 minutes max)
160 
161## Content Type Decision Guide
162 
163**When to use each content type:**
164 
165| Content Type | Use When | Readable By | Supports |
166|--------------|----------|-------------|----------|
167| `json` (default) | Pull consumers, dashboard visibility, simple objects | All (push/pull/dashboard) | JSON-serializable types only |
168| `v8` | Push consumers only, complex JS objects | Push consumers only | Date, Map, Set, BigInt, typed arrays |
169| `text` | String-only payloads | All | Strings only |
170| `bytes` | Binary data (images, files) | All | ArrayBuffer, Uint8Array |
171 
172**Decision tree:**
1731. Need to view in dashboard or use pull consumer? → Use `json`
1742. Need Date, Map, Set, or other V8 types? → Use `v8` (push consumers only)
1753. Just strings? → Use `text`
1764. Binary data? → Use `bytes`
177 
178```typescript
179// Dashboard/pull: use json
180await env.QUEUE.send({ id: 123, name: 'test' }, { contentType: 'json' });
181 
182// Complex JS types (push only): use v8
183await env.QUEUE.send({ 
184  created: new Date(), 
185  tags: new Set(['a', 'b']) 
186}, { contentType: 'v8' });
187```
188 
189## Limits
190 
191| Limit | Value | Notes |
192|-------|-------|-------|
193| Max queues | 10,000 | Per account |
194| Message size | 128 KB | Maximum per message |
195| Batch size (consumer) | 100 messages | Maximum messages per batch |
196| Batch size (sendBatch) | 100 msgs or 256 KB | Whichever limit reached first |
197| Throughput | 5,000 msgs/sec | Per queue |
198| Retention | 4-14 days | Configurable retention period |
199| Max backlog | 25 GB | Maximum queue backlog size |
200| Max delay | 12 hours (43,200s) | Maximum message delay |
201| Max retries | 100 | Maximum retry attempts |
202| CPU time default | 30s | Per consumer invocation |
203| CPU time max | 300s (5 min) | Configurable via `limits.cpu_ms` |
204| Operations per message | 3 (write + read + delete) | Base cost per message |
205| Pricing | $0.40 per 1M operations | After 1M free operations |
206| Message charging | Per 64 KB chunk | Messages charged in 64 KB increments |
207