{"record":{"id":"9e24cf3a1e022e01","repo":"paperclipai/paperclip","slug":"verified-runtime-executable-target-descriptor-is-i","errorCode":null,"errorMessage":"Verified runtime executable target descriptor is invalid","messagePattern":"Verified runtime executable target descriptor is invalid","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/verified-runtime-executable.ts","lineNumber":64,"sourceCode":"\n  throw new Error(\n    \"Verified runtime executable is unsupported on this platform\",\n  );\n}\n\n/**\n * Project the current verified runtime into a chosen child descriptor. The\n * caller must place sourceFd at child targetFd in its stdio table.\n */\nexport function verifiedRuntimeExecutableHandoff(\n  targetFd: number,\n  environment: NodeJS.ProcessEnv = process.env,\n  platform: NodeJS.Platform = process.platform,\n  currentPid: number = process.pid,\n  fallback: string = process.execPath,\n): VerifiedRuntimeExecutableHandoff {\n  if (!Number.isSafeInteger(targetFd) || targetFd < 3) {\n    throw new Error(\"Verified runtime executable target descriptor is invalid\");\n  }\n  const executable = verifiedRuntimeExecutable(\n    environment,\n    platform,\n    currentPid,\n    fallback,\n  );\n  const configured = environment[VERIFIED_RUNTIME_EXECUTABLE_ENV];\n  if (platform !== \"linux\" || configured === undefined) {\n    return {\n      executable,\n      environmentValue: configured === undefined ? undefined : executable,\n      sourceFd: null,\n    };\n  }\n  const match = /^\\/proc\\/self\\/fd\\/([0-9]+)$/.exec(configured);\n  if (match === null) {\n    throw new Error(\"Verified runtime executable descriptor is invalid\");","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/verified-runtime-executable.ts#L46-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nconst handoff = verifiedRuntimeExecutableHandoff(1); // stdio slot\n// after\nconst targetFd = 3;\nif (!Number.isSafeInteger(targetFd) || targetFd < 3) throw new Error(\"bad fd\");\nconst handoff = verifiedRuntimeExecutableHandoff(targetFd);","handlingStrategy":"validation","validationCode":"function assertValidTargetFd(fd) {\n  if (!Number.isSafeInteger(fd) || fd < 3) {\n    throw new Error(`targetFd must be an integer >= 3, got ${fd}`);\n  }\n}","typeGuard":"function isUsableTargetFd(fd) {\n  return typeof fd === \"number\" && Number.isSafeInteger(fd) && fd >= 3;\n}","tryCatchPattern":"try {\n  const handoff = verifiedRuntimeExecutableHandoff(targetFd);\n} catch (err) {\n  if (err.message === \"Verified runtime executable target descriptor is invalid\") {\n    return verifiedRuntimeExecutableHandoff(3, /* env */); // use first spare fd\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["fd","validation","argument","handoff"],"backgroundTag":"value-out-of-range","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}