What causes "Verified runtime executable target descriptor is invalid" in paperclipai/paperclip?

Pass a targetFd of 3 or higher that corresponds to a spare slot in the child's stdio table

Verified runtime executable target descriptor is invalid

Error message

Verified runtime executable target descriptor is invalid

What it means

verifiedRuntimeExecutableHandoff(targetFd, ...) projects the current verified runtime into a child's descriptor at targetFd, which must be a safe integer >= 3 (0-2 are stdio). This error is thrown for an invalid targetFd before any executable resolution happens.

Source

Thrown at packages/paperclip-runner/src/drivers/acpx/verified-runtime-executable.ts:64

  throw new Error(
    "Verified runtime executable is unsupported on this platform",
  );
}

/**
 * Project the current verified runtime into a chosen child descriptor. The
 * caller must place sourceFd at child targetFd in its stdio table.
 */
export function verifiedRuntimeExecutableHandoff(
  targetFd: number,
  environment: NodeJS.ProcessEnv = process.env,
  platform: NodeJS.Platform = process.platform,
  currentPid: number = process.pid,
  fallback: string = process.execPath,
): VerifiedRuntimeExecutableHandoff {
  if (!Number.isSafeInteger(targetFd) || targetFd < 3) {
    throw new Error("Verified runtime executable target descriptor is invalid");
  }
  const executable = verifiedRuntimeExecutable(
    environment,
    platform,
    currentPid,
    fallback,
  );
  const configured = environment[VERIFIED_RUNTIME_EXECUTABLE_ENV];
  if (platform !== "linux" || configured === undefined) {
    return {
      executable,
      environmentValue: configured === undefined ? undefined : executable,
      sourceFd: null,
    };
  }
  const match = /^\/proc\/self\/fd\/([0-9]+)$/.exec(configured);
  if (match === null) {
    throw new Error("Verified runtime executable descriptor is invalid");

View on GitHub (pinned to 01ad858492)

Solutions

Pass a targetFd of 3 or higher that corresponds to a spare slot in the child's stdio table
Validate the fd is a safe integer >= 3 before calling (Number.isSafeInteger(fd) && fd >= 3)
Fix any string-to-number parsing of fd values (use parseInt with radix and validate)
Ensure the caller places sourceFd (returned in the result) at targetFd in the child stdio array

Example fix

// before
const handoff = verifiedRuntimeExecutableHandoff(1); // stdio slot
// after
const targetFd = 3;
if (!Number.isSafeInteger(targetFd) || targetFd < 3) throw new Error("bad fd");
const handoff = verifiedRuntimeExecutableHandoff(targetFd);

Defensive patterns

Strategy: validation

Validate before calling

function assertValidTargetFd(fd) {
  if (!Number.isSafeInteger(fd) || fd < 3) {
    throw new Error(`targetFd must be an integer >= 3, got ${fd}`);
  }
}

Type guard

function isUsableTargetFd(fd) {
  return typeof fd === "number" && Number.isSafeInteger(fd) && fd >= 3;
}

Try / catch

try {
  const handoff = verifiedRuntimeExecutableHandoff(targetFd);
} catch (err) {
  if (err.message === "Verified runtime executable target descriptor is invalid") {
    return verifiedRuntimeExecutableHandoff(3, /* env */); // use first spare fd
  }
  throw err;
}

Prevention

Always allocate fds 3+ for the descriptor, never stdio slots 0-2
Parse fd values from config with parseInt and validate before use
Reserve fd 3 explicitly in your child stdio table layout
Add a unit test covering fd validation boundaries

When it happens

Trigger: Calling verifiedRuntimeExecutableHandoff with targetFd 0, 1, 2, a negative number, a non-integer (e.g. 3.5 or NaN), or a value exceeding Number.MAX_SAFE_INTEGER.

Common situations: Off-by-one stdio table construction where stdio slots are passed by mistake; parsing the fd from config/string without validation; defaulting targetFd to 0/1 accidentally.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/9e24cf3a1e022e01. Report an issue: GitHub.