{"record":{"id":"a1b52bcdab9d4712","repo":"stablyai/orca","slug":"invalid-serve-port-value-rawport","errorCode":null,"errorMessage":"Invalid --serve-port value: ${rawPort}","messagePattern":"Invalid --serve-port value: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/main/index.ts","lineNumber":1835,"sourceCode":"  recipeJson: boolean\n  projectRoot: string | null\n}\n\nfunction getServeOptions(argv = process.argv): ServeOptions {\n  const valueAfter = (flag: string): string | null => {\n    const index = argv.indexOf(flag)\n    if (index === -1) {\n      return null\n    }\n    const value = argv[index + 1]\n    return value && !value.startsWith('--') ? value : null\n  }\n  const rawPort = valueAfter('--serve-port')\n  let wsPort: number | undefined\n  if (rawPort) {\n    const parsedPort = Number(rawPort)\n    if (!Number.isInteger(parsedPort) || parsedPort < 0 || parsedPort > 65535) {\n      throw new Error(`Invalid --serve-port value: ${rawPort}`)\n    }\n    wsPort = parsedPort\n  }\n  return {\n    json: argv.includes('--serve-json'),\n    ...(wsPort !== undefined ? { wsPort } : {}),\n    pairingAddress: valueAfter('--serve-pairing-address'),\n    noPairing: argv.includes('--serve-no-pairing'),\n    mobilePairing: argv.includes('--serve-mobile-pairing'),\n    recipeJson: argv.includes('--serve-recipe-json'),\n    projectRoot: valueAfter('--serve-project-root')\n  }\n}\n\nfunction getBundledWebClientRoot(): string | undefined {\n  const appPath = app.getAppPath()\n  const roots = [\n    join(appPath, 'out', 'web'),","sourceCodeStart":1817,"sourceCodeEnd":1853,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/index.ts#L1817-L1853","documentation":"Thrown during CLI argument parsing when --serve-port is present but its value is not an integer in the range [0, 65535]. The parser uses Number(rawPort) and rejects NaN, floats, negatives, and values above 65535. Fails fast at startup so the WebSocket server never binds to an invalid port.","triggerScenarios":"Launching with `--serve-port abc`, `--serve-port 8080.5`, `--serve-port -1`, `--serve-port 70000`, or omitting the value such that the next token is another flag (valueAfter returns null, but if a non-numeric token follows it is parsed). Anywhere a port is sourced from an env var or script without validation.","commonSituations":"Typo in the port number; sourcing --serve-port from an env var that is empty or non-numeric; passing a service name instead of a port; copy-paste from a config that used a port above 65535.","solutions":["Supply an integer port in [0, 65535], e.g. `--serve-port 8787`.","If the port comes from an env var, validate it in the launching script before forwarding to --serve-port.","For ephemeral binding, pick 0 (the OS assigns a free port)."],"exampleFix":"// before\nconst parsedPort = Number(rawPort)\nif (!Number.isInteger(parsedPort) || parsedPort < 0 || parsedPort > 65535) {\n  throw new Error(`Invalid --serve-port value: ${rawPort}`)\n}\n// after — clearer error naming the constraint\nconst parsedPort = Number(rawPort)\nif (!Number.isInteger(parsedPort) || parsedPort < 0 || parsedPort > 65535) {\n  throw new Error(`Invalid --serve-port value: ${rawPort}. Must be an integer in [0, 65535].`)\n}","handlingStrategy":"validation","validationCode":"function isValidPort(value: string): boolean {\n  const n = Number(value)\n  return Number.isInteger(n) && n >= 0 && n <= 65535\n}","typeGuard":"function isValidServePort(rawPort: unknown): rawPort is string {\n  return typeof rawPort === 'string' && /^\\d+$/.test(rawPort)\n    && Number.isInteger(Number(rawPort)) && Number(rawPort) >= 0 && Number(rawPort) <= 65535\n}","tryCatchPattern":null,"preventionTips":["Validate ports from env vars in the launching script before forwarding to --serve-port.","Prefer well-known free ports and document a recommended default.","Reject non-numeric tokens early in CLI wrappers."],"tags":["cli","validation","port","serve","args"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}