fix: surface worker startup stderr

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: yuranich

packages/sdk/client/rpc/node-rpc-client.ts

@@ -22,6 +22,7 @@ import {
 import type { RuntimeContext } from "@/schemas";
 
 const RPC_INIT_TIMEOUT_MS = 30_000;
+const WORKER_STDERR_TAIL_CHARS = 16_384;
 
 const logger = getClientLogger();
 
@@ -175,6 +176,19 @@ function bestEffortUnlinkSocket(socketPath: string | null) {
   }
 }
 
+function appendWorkerStderrTail(current: string, chunk: string) {
+  const next = current + chunk;
+  if (next.length <= WORKER_STDERR_TAIL_CHARS) return next;
+  return next.slice(next.length - WORKER_STDERR_TAIL_CHARS);
+}
+
+function createWorkerStartupError(details: string, stderrTail: string) {
+  const stderr = stderrTail.trimEnd();
+  if (!stderr) return new Error(details);
+
+  return new Error(`${details}\n\nWorker stderr:\n${stderr}`);
+}
+
 function resetModuleState() {
   rpcInstance = null;
   rpcPromise = null;
@@ -230,6 +244,14 @@ interface SpawnResources {
   socketPath: string;
 }
 
+interface WorkerStderrStream {
+  on(event: "data", listener: (chunk: Buffer | string) => void): void;
+}
+
+function getWorkerStderr(proc: BareChildProcess): WorkerStderrStream | null {
+  return (proc as { stderr?: WorkerStderrStream | null }).stderr ?? null;
+}
+
 // `bare-runtime` resolves its platform binary with
 // `require('bare-runtime-<platform>-<arch>')` and throws a terse
 // `No binaries found for target '<platform>-<arch>'` whenever that package —
@@ -322,12 +344,19 @@ async function ensureRPC(): Promise<RPC> {
 
   rpcPromise = new Promise((resolve, reject) => {
     let settled = false;
+    let workerStderrTail = "";
 
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
+      const cause = workerStderrTail
+        ? createWorkerStartupError(
+            "Worker did not establish IPC before the RPC initialization timeout",
+            workerStderrTail,
+          )
+        : undefined;
       teardownFailedInit();
-      reject(new RPCInitTimeoutError(RPC_INIT_TIMEOUT_MS));
+      reject(new RPCInitTimeoutError(RPC_INIT_TIMEOUT_MS, cause));
     }, RPC_INIT_TIMEOUT_MS);
 
     ipcServer = createServer((socket) => {
@@ -370,7 +399,7 @@ async function ensureRPC(): Promise<RPC> {
           ],
           platform: process.platform,
           arch: process.arch,
-          stdio: ["inherit", "inherit", "inherit"],
+          stdio: ["inherit", "inherit", "pipe"],
         });
       } catch (error) {
         // `spawn` resolves the bare binary synchronously and can throw before
@@ -386,6 +415,12 @@ async function ensureRPC(): Promise<RPC> {
       }
 
       if (bareWorkerProc) {
+        getWorkerStderr(bareWorkerProc)?.on("data", (chunk) => {
+          const text = chunk.toString();
+          workerStderrTail = appendWorkerStderrTail(workerStderrTail, text);
+          process.stderr.write(chunk);
+        });
+
         bareWorkerProc.on(
           "exit",
           (code: number | null, exitSignal: string | null) => {
@@ -397,15 +432,29 @@ async function ensureRPC(): Promise<RPC> {
               );
               return;
             }
-            // Worker died before handshake — reject the init promise.
+            // Pre-handshake failures are rejected from "close" so stderr has
+            // drained before we assemble the startup error cause.
+          },
+        );
+
+        bareWorkerProc.on(
+          "close",
+          (...args: unknown[]) => {
+            if (settled) return;
+            const code = typeof args[0] === "number" ? args[0] : null;
+            const exitSignal = typeof args[1] === "string" ? args[1] : null;
+
+            // Worker died before handshake. Use close, not exit, so piped
+            // stderr has drained before we build the error cause.
             settled = true;
             clearTimeout(timer);
             teardownFailedInit();
             reject(
               new RPCInitTimeoutError(
                 RPC_INIT_TIMEOUT_MS,
-                new Error(
-                  `Worker process exited with code ${code} before IPC connection was established`,
+                createWorkerStartupError(
+                  `Worker process exited with code ${code}, signal ${exitSignal} before IPC connection was established`,
+                  workerStderrTail,
                 ),
               ),
             );

packages/sdk/scripts/repro-worker-startup-error.ts

@@ -0,0 +1,84 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const nativeLoadErrorMarker = "QVAC_REPRO_NATIVE_LOAD_ERROR";
+
+function formatCause(error: Error | undefined) {
+  const cause = (error as { cause?: unknown } | undefined)?.cause;
+  if (!cause) return "<none>";
+  if (cause instanceof Error) return `${cause.name}: ${cause.message}`;
+  if (typeof cause === "string") return cause;
+  return Object.prototype.toString.call(cause);
+}
+
+function collectMessages(error: Error | undefined) {
+  if (!error) return "";
+
+  const cause = (error as { cause?: unknown }).cause;
+  const causeMessage =
+    cause instanceof Error ? cause.message : Object.prototype.toString.call(cause);
+  return `${error.message}\n${causeMessage}`;
+}
+
+async function main() {
+  process.env["QVAC_WORKER_PATH"] = path.resolve(
+    __dirname,
+    "../test/unit/fixtures/native-load-failure-worker.mjs",
+  );
+
+  const { loadModel } = await import("../client/api/load-model");
+  const { close } = await import("../client/rpc/rpc-client");
+
+  let startupError: Error | undefined;
+  try {
+    await loadModel({
+      modelSrc: "/tmp/qvac-repro-model.gguf",
+      modelType: "llamacpp-completion",
+    });
+  } catch (error) {
+    startupError = error as Error;
+  }
+
+  try {
+    await close();
+  } catch {}
+
+  if (!startupError) {
+    console.error("Expected loadModel() to fail, but it resolved.");
+    process.exit(1);
+  }
+
+  const name = (startupError as { name?: string }).name;
+  const messages = collectMessages(startupError);
+
+  if (name !== "RPC_INIT_TIMEOUT") {
+    console.error(`Expected RPC_INIT_TIMEOUT, got ${name ?? "<missing>"}.`);
+    console.error(startupError);
+    process.exit(1);
+  }
+
+  console.log("\n=== SDK-facing error caught by the caller ===");
+  console.log(`name: ${name}`);
+  console.log(`message: ${startupError.message}`);
+  console.log(`cause: ${formatCause(startupError)}`);
+
+  if (!messages.includes(nativeLoadErrorMarker)) {
+    console.error(
+      `Expected SDK error details to include ${nativeLoadErrorMarker}.`,
+    );
+    process.exit(1);
+  }
+
+  console.log("\n=== Reproduction result ===");
+  console.log("Fixed: loadModel() failed with RPC_INIT_TIMEOUT.");
+  console.log(
+    `The SDK error includes the underlying ${nativeLoadErrorMarker} marker.`,
+  );
+  process.exit(0);
+}
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exit(1);
+});

packages/sdk/test/unit/fixtures/native-load-failure-worker.mjs

@@ -0,0 +1,3 @@
+// Bare worker that fails before the IPC handshake, like a native addon dlopen error.
+
+throw new Error('QVAC_REPRO_NATIVE_LOAD_ERROR: simulated dlopen failure before worker handshake')