${action} failed with exit code ${result.exitCode ?? "null"}

Error message

${action} failed with exit code ${result.exitCode ?? "null"}${result.stderr.trim() ? `: ${result.stderr.trim()}` : ""}

What it means

Thrown by the Cloudflare bridge's `requireZeroExit` (routes.ts:121) when a lease-utility command finishes with a non-zero `exitCode` (and did not time out). The action label (e.g. `ensure workspace <dir>`, `write sentinel <path>`) and the trimmed stderr are embedded so the failing setup step is identifiable.

Source

Thrown at packages/plugins/sandbox-providers/cloudflare/bridge-template/src/routes.ts:121

  cwd = "/",
) {
  return await executeInSandbox({
    sandbox,
    command,
    args,
    cwd,
    timeoutMs: options.timeoutMs,
    sessionStrategy: options.sessionStrategy,
    sessionId: options.sessionId,
  });
}

function requireZeroExit(action: string, result: { exitCode: number | null; timedOut: boolean; stderr: string }) {
  if (result.timedOut) {
    throw new Error(`${action} timed out: ${result.stderr.trim()}`);
  }
  if (result.exitCode !== 0) {
    throw new Error(
      `${action} failed with exit code ${result.exitCode ?? "null"}${result.stderr.trim() ? `: ${result.stderr.trim()}` : ""}`,
    );
  }
}

async function ensureWorkspace(
  sandbox: CloudflareSandbox,
  options: {
    remoteCwd: string;
    sessionStrategy: SessionStrategy;
    sessionId: string;
    timeoutMs: number;
  },
) {
  const result = await execLeaseUtility(sandbox, options, "mkdir", ["-p", options.remoteCwd], "/");
  requireZeroExit(`ensure workspace ${options.remoteCwd}`, result);
}

View on GitHub (pinned to 67001ec6eb)

Solutions

Inspect the embedded action label and stderr in the message to identify which step failed (workspace mkdir vs sentinel write).
Use a `remoteCwd`/`requestedCwd` that is absolute and writable inside the sandbox image.
Ensure the sandbox base image ships a POSIX shell and coreutils (`mkdir`, `printf`, `test`).

Example fix

// before
requestedCwd: "/proc/something"
// after
requestedCwd: "/workspace"

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate cwd shape before sending; the bridge will mkdir -p it.
function assertWritableRemoteCwd(cwd) {
  if (typeof cwd !== "string" || cwd.length === 0) throw new TypeError("remoteCwd required");
  if (!cwd.startsWith("/")) throw new TypeError("remoteCwd must be absolute");
  return cwd;
}

Try / catch

try {
  await client.acquireLease(body);
} catch (err) {
  if (err instanceof Error && /failed with exit code/.test(err.message)) {
    // inspect embedded action label + stderr; fix remoteCwd/image and retry
  } else throw err;
}

Prevention

Use an absolute, writable remoteCwd inside the sandbox image.
Ensure the image ships sh + coreutils (mkdir, printf, test).
Read the action label in the message to localize the failing setup step.

When it happens

Trigger: An internal bridge setup command fails: `mkdir -p <remoteCwd>` returns non-zero (permissions/path issue), or the sentinel write/printf command fails. The error propagates out of `ensureWorkspace`/`writeSentinel` during acquire/resume/probe.

Common situations: The requested `remoteCwd` is not writable or is an invalid path inside the sandbox; the sandbox image lacks the shell/utilities the wrapper assumes (`sh`, `printf`, `mkdir`); or a read-only filesystem blocks the sentinel file write.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/38f10a5b8d4084ff. Report an issue: GitHub.