paperclipai/paperclip · error

Verified runtime executable is unsupported on this platform

Error message

Verified runtime executable is unsupported on this platform

What it means

verifiedRuntimeExecutable() only supports the Linux (/proc/self/fd descriptor) and macOS (exact execPath) verified-handoff schemes. On any other platform, when the handoff env var is set, the function throws this error because no verified-executable recovery scheme exists there.

Source

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

    throw new Error("Verified runtime executable descriptor is invalid");
  }

  if (platform === "darwin") {
    if (
      !isAbsolute(fallback) ||
      resolve(fallback) !== fallback ||
      configured !== fallback
    ) {
      throw new Error("Verified runtime executable path is invalid");
    }
    // The Rust supervisor materializes the authenticated runtime as a private,
    // read-only executable and starts this process from that exact pathname.
    // Descendants may inherit the handoff variable, but they cannot nominate a
    // different absolute path and have it treated as verified.
    return fallback;
  }

  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");
  }

View on GitHub (pinned to 01ad858492)

Solutions

1. Unset PAPERCLIP_VERIFIED_RUNTIME_EXECUTABLE on unsupported platforms so the fallback execPath is used
2. Gate env-var export on process.platform being linux or darwin
3. Run the runner under Linux/macOS when verified-executable handoff is required
4. Use platform-conditional setup in CI so the variable is only exported on supported OSes

Example fix

// before
env.PAPERCLIP_VERIFIED_RUNTIME_EXECUTABLE = fdPath; // exported everywhere
// after
if (process.platform === "linux" || process.platform === "darwin") {
  env.PAPERCLIP_VERIFIED_RUNTIME_EXECUTABLE = fdPath;
}

if (process.env.PAPERCLIP_VERIFIED_RUNTIME_EXECUTABLE !== undefined &&
    !['linux','darwin'].includes(process.platform)) {
  delete process.env.PAPERCLIP_VERIFIED_RUNTIME_EXECUTABLE;
}

function platformSupportsVerifiedHandoff(p) {
  return p === "linux" || p === "darwin";
}

try {
  const exe = verifiedRuntimeExecutable();
} catch (err) {
  if (err.message.includes("unsupported on this platform")) {
    const { [VERIFIED_RUNTIME_EXECUTABLE_ENV]: _omit, ...clean } = process.env;
    return verifiedRuntimeExecutable(clean);
  }
  throw err;
}

When it happens

Trigger: Running on Windows (or another non-linux/darwin platform) with PAPERCLIP_VERIFIED_RUNTIME_EXECUTABLE set in the environment; a CI matrix executing Linux-specific handoff config on an unsupported OS.

Common situations: Windows dev machines inheriting env vars from shared dotfiles/containers; a generic launcher exporting the env var unconditionally across platforms; WSL/Windows boundary leaking the variable.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• Service management is not supported on ${platform}. Use pape
• managed_profile_not_found
• managed_profile_unavailable
• agentcore_profile_unavailable
• Database mode is postgres but no connection string was set;

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