fix(void): log queue handler errors instead of dropping them (#629)

## Summary

When a queue handler throws, its error is never logged. The generated
`__processQueue` catches it without binding it (`} catch { __ok = false;
}`), so the reason is lost on every path:

- Native Cloudflare consumers: the Worker's `queue()` throws a new
`Error("queue: Handler failed.")`, and Workers Logs and `void project
logs` show only that.
- Dev: `/__void/queue` answers `{"ok":false}`, and nothing reaches the
terminal.
- Void Cloud: the relay gets a 200 `{"ok":false}` and retries the batch,
and nothing is logged.

The generated `scheduled()` already logs a failing job's error (`[void]
Scheduled job … failed for cron "…"`). `__processQueue` in
`packages/void/src/router/compile.ts` now does the same for queue
handlers before marking the batch failed, which covers all three paths.
When no handler matches the queue, `__processQueue` returned the reason
only as `error`, which the native `queue()` dropped and the Void Cloud
relay ignores, so it now logs that reason too. `handleQueueRelay` in
`packages/void/src/cli/wrapper.ts` had the same `catch` and now logs
too. The wrapper's native `queue()` already lets errors through, and the
framework dev trigger already logs them (`[void] queue handler threw:`).

The thrown `queue: Handler failed.`, the `{ ok: false }` result and the
ack/retry decisions are unchanged. `docs/guide/queues.md` now says the
handler's error is logged.

## Repro

1. `queues/fail.ts`:
   ```ts
   import { defineQueue } from 'void';

   export default defineQueue(async () => {
     throw new Error('boom');
   });
   ```
2. Start the dev server, then send it a message with the token it
prints:
   ```sh
   curl -X POST http://localhost:5173/__void/queue \
     -H "x-void-dev-trigger: <token>" \
-d
'{"queue":"fail","messages":[{"id":"1","timestamp":0,"body":{},"attempts":1}]}'
   ```

- Before: the response is `{"ok":false}`, and `boom` is logged nowhere.
- After: the response is unchanged, and the terminal shows `[void] Queue
handler queues/fail.ts failed for queue "fail": Error: boom` with its
stack. A message sent through the queue binding (Miniflare's native
delivery) logs the same line.

## Tests

- `packages/void/test/integration/queue-dispatch.test.ts`: the error a
handler throws reaches `console.error` as the same object, with its file
and queue, through `__processQueue` and through the native `queue()`.
Both also log the reason for an unknown queue.
- `packages/void/test/unit/wrapper.test.ts`: the same for the wrapper's
HTTP relay.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: morinokami

docs/guide/queues.md

@@ -76,7 +76,7 @@ export default defineQueue<Message>(async (batch, env) => {
 - `batch.ackAll()`: acknowledge all messages in the batch
 - `batch.retryAll(options?)`: retry all messages in the batch
 
-The first call wins for each message. Calling `ack()` after `retry()`, or the reverse, does nothing. Messages with no explicit decision are acknowledged if the handler succeeds, or retried if it throws.
+The first call wins for each message. Calling `ack()` after `retry()`, or the reverse, does nothing. Messages with no explicit decision are acknowledged if the handler succeeds, or retried if it throws. The handler's error is logged, so you don't need to catch errors just to log them.
 
 The `timestamp` field on each message is a `Date` object.
 

packages/void/src/cli/wrapper.ts

@@ -903,7 +903,12 @@ export async function handleQueueRelay(payload, env, ctx) {
     retryAll(options) { for (const message of messages) message.retry(options); },
   };
   let ok = true;
-  try { await handleQueue(batch, env, ctx); } catch { ok = false; }
+  try {
+    await handleQueue(batch, env, ctx);
+  } catch (error) {
+    console.error(\`[void] Queue handler failed for queue "\${payload.queue}":\`, error);
+    ok = false;
+  }
   return { ok, ...(decisions.size ? { decisions: Object.fromEntries(decisions) } : {}) };
 }`);
   }

packages/void/src/router/compile.ts

@@ -553,15 +553,23 @@ export function compileRouteTable(
       ),
     );
     lines.push('');
+    const queueLabels = scan.queues.map((queue) =>
+      relative(options.projectRoot, `${queuesDir}/${queue.filePath}`),
+    );
+    lines.push(`const __queueLabels = ${JSON.stringify(queueLabels)};`);
     // Queue dispatch as a standalone function — called directly by native queue handler
     // and via the authenticated HTTP route. No global mutable state needed.
+    // It logs why a batch failed: the native handler throws only "queue: Handler failed.",
+    // the HTTP route returns no handler error, and the Void Cloud relay ignores `error`.
     lines.push('export async function __processQueue(payload, env) {');
     lines.push('  const queueSuffix = payload.queue;');
     lines.push('  const __queueIndex = __resolveQueueIndex(queueSuffix);');
     lines.push('  if (__queueIndex === -1) {');
     lines.push(
-      '    return { ok: false, error: `No unambiguous queue handler matches "${String(queueSuffix)}"` };',
+      '    const __error = `No unambiguous queue handler matches "${String(queueSuffix)}"`;',
     );
+    lines.push('    console.error(`[void] ${__error}`);');
+    lines.push('    return { ok: false, error: __error };');
     lines.push('  }');
     lines.push('  const __decisions = new Map();');
     lines.push('  function __wrapMsg(m) {');
@@ -599,7 +607,12 @@ export function compileRouteTable(
       lines.push('      }');
     }
     lines.push('    }');
-    lines.push('  } catch { __ok = false; }');
+    lines.push('  } catch (error) {');
+    lines.push(
+      '    console.error(`[void] Queue handler ${__queueLabels[__queueIndex]} failed for queue "${String(queueSuffix)}":`, error);',
+    );
+    lines.push('    __ok = false;');
+    lines.push('  }');
     lines.push(
       '  return { ok: __ok, ...(__decisions.size > 0 ? { decisions: Object.fromEntries(__decisions) } : {}) };',
     );

packages/void/test/integration/queue-dispatch.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { build } from 'vite';
-import { afterAll, beforeAll, describe, expect, it, vi } from 'vite-plus/test';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vite-plus/test';
 import { compileRouteTable, compileWorkerEntry } from '../../src/router/compile.ts';
 import type { ScanResult } from '../../src/router/scan.ts';
 
@@ -37,7 +37,7 @@ function queueHandlerSource(handler: string): string {
     attempts: batch.messages.map(message => message.attempts),
     dates: batch.messages.every(message => message.timestamp instanceof Date),
   });
-  if (env.fail === ${JSON.stringify(handler)}) throw new Error("handler failed");
+  if (env.fail === ${JSON.stringify(handler)}) throw env.failure;
   batch.messages[0]?.ack();
   batch.messages[1]?.retry({ delaySeconds: 9 });
 }\n`;
@@ -159,6 +159,10 @@ export { __processQueue } from "virtual:void-routes";\n`,
     rmSync(temporary, { force: true, recursive: true });
   });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   it.each([
     ['emails', 'emails'],
     ['order-emails', 'order-emails'],
@@ -179,7 +183,8 @@ export { __processQueue } from "virtual:void-routes";\n`,
     expect(env.calls).toEqual([{ handler: expectedHandler, queue, attempts: [2, 3], dates: true }]);
   });
 
-  it('returns failure without dispatching an unknown logical or physical queue', async () => {
+  it('logs and returns failure without dispatching an unknown logical or physical queue', async () => {
+    const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
     for (const queue of ['unknown', 'project-unknown']) {
       const env = { calls: [] as Array<Record<string, unknown>> };
       const result = await generated.__processQueue(payload(queue), env);
@@ -190,6 +195,27 @@ export { __processQueue } from "virtual:void-routes";\n`,
       });
       expect(env.calls).toEqual([]);
     }
+    expect(errorLog.mock.calls).toEqual([
+      ['[void] No unambiguous queue handler matches "unknown"'],
+      ['[void] No unambiguous queue handler matches "project-unknown"'],
+    ]);
+  });
+
+  it('logs a failed handler with its file and queue and returns failure', async () => {
+    const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const failure = new Error('handler failed');
+    const env = { calls: [] as Array<Record<string, unknown>>, fail: 'order-emails', failure };
+    const result = await generated.__processQueue(payload('project-order-emails'), env);
+
+    expect(result).toEqual({ ok: false });
+    expect(env.calls).toEqual([
+      { handler: 'order-emails', queue: 'project-order-emails', attempts: [2, 3], dates: true },
+    ]);
+    expect(errorLog.mock.calls).toHaveLength(1);
+    expect(errorLog.mock.calls[0][0]).toBe(
+      '[void] Queue handler queues/order-emails.ts failed for queue "project-order-emails":',
+    );
+    expect(errorLog.mock.calls[0][1]).toBe(failure);
   });
 
   it.each(['emails', 'order-emails'])(
@@ -219,6 +245,8 @@ export { __processQueue } from "virtual:void-routes";\n`,
   );
 
   it('makes native unknown queues and handler failures retry by rejecting the event', async () => {
+    const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const failure = new Error('handler failed');
     const makeNativeBatch = (queue: string) => {
       const firstAck = vi.fn();
       const firstRetry = vi.fn();
@@ -270,6 +298,7 @@ export { __processQueue } from "virtual:void-routes";\n`,
     expect(nativeSuccess.firstRetry).not.toHaveBeenCalled();
     expect(nativeSuccess.secondAck).not.toHaveBeenCalled();
     expect(nativeSuccess.secondRetry).toHaveBeenCalledWith({ delaySeconds: 9 });
+    expect(errorLog).not.toHaveBeenCalled();
 
     const nativeUnknown = makeNativeBatch('project-unknown');
 
@@ -285,9 +314,17 @@ export { __processQueue } from "virtual:void-routes";\n`,
     await expect(
       generated.default.queue(
         nativeFailure.batch,
-        { calls: [], fail: 'order-emails' },
+        { calls: [], fail: 'order-emails', failure },
         {} as ExecutionContext,
       ),
     ).rejects.toThrow('queue: Handler failed');
+    expect(errorLog.mock.calls).toHaveLength(2);
+    expect(errorLog.mock.calls[0]).toEqual([
+      '[void] No unambiguous queue handler matches "project-unknown"',
+    ]);
+    expect(errorLog.mock.calls[1][0]).toBe(
+      '[void] Queue handler queues/order-emails.ts failed for queue "project-order-emails":',
+    );
+    expect(errorLog.mock.calls[1][1]).toBe(failure);
   });
 });

packages/void/test/unit/wrapper.test.ts

@@ -387,6 +387,7 @@ describe('generated wrapper queue dispatch', () => {
     for (const root of roots.splice(0, roots.length)) {
       rmSync(root, { recursive: true, force: true });
     }
+    vi.restoreAllMocks();
   });
 
   async function createRelayWorker() {
@@ -402,7 +403,7 @@ describe('generated wrapper queue dispatch', () => {
       `export default function(batch, env) {
       env.calls.push(batch.messages[0].timestamp.getTime());
       batch.messages[0].ack();
-      if (env.fail) throw new Error('after first message');
+      if (env.fail) throw env.fail;
       batch.messages[0].retry();
       batch.messages[1].retry({ delaySeconds: 9 });
       batch.ackAll();
@@ -435,6 +436,7 @@ describe('generated wrapper queue dispatch', () => {
 
   it('delivers managed HTTP batches and returns first-wins acknowledgment decisions', async () => {
     const worker = await createRelayWorker();
+    const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
     const env = { __VOID_PROXY_TOKEN: 'token', calls: [] as Array<number> };
     const response = await worker.fetch(relayRequest('token'), env, {});
     expect(response.status).toBe(200);
@@ -446,8 +448,13 @@ describe('generated wrapper queue dispatch', () => {
       },
     });
     expect(env.calls).toEqual([Date.parse('2026-01-01T00:00:00Z')]);
-    const failed = await worker.fetch(relayRequest('token'), { ...env, fail: true }, {});
+    expect(errorLog).not.toHaveBeenCalled();
+    const failure = new Error('after first message');
+    const failed = await worker.fetch(relayRequest('token'), { ...env, fail: failure }, {});
     expect(await failed.json()).toEqual({ ok: false, decisions: { one: { action: 'ack' } } });
+    expect(errorLog.mock.calls).toHaveLength(1);
+    expect(errorLog.mock.calls[0][0]).toBe('[void] Queue handler failed for queue "emails":');
+    expect(errorLog.mock.calls[0][1]).toBe(failure);
     expect((await worker.fetch(new Request('https://worker/__void/ready'), env, {})).status).toBe(
       200,
     );