{"record":{"id":"86298e65bd68fec0","repo":"stablyai/orca","slug":"invalid-argument-86298e","errorCode":"invalid_argument","errorMessage":"Recipe JSON output requires --project-root.","messagePattern":"Recipe JSON output requires --project-root\\.","errorType":"validation","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/runtime/launch.ts","lineNumber":111,"sourceCode":"  childArgs.push('--serve')\n  if (args.json) {\n    childArgs.push('--serve-json')\n  }\n  if (args.port) {\n    childArgs.push('--serve-port', args.port)\n  }\n  if (args.pairingAddress) {\n    childArgs.push('--serve-pairing-address', args.pairingAddress)\n  }\n  if (args.noPairing) {\n    childArgs.push('--serve-no-pairing')\n  }\n  if (args.mobilePairing) {\n    childArgs.push('--serve-mobile-pairing')\n  }\n  if (args.recipeJson) {\n    if (!args.projectRoot) {\n      throw new RuntimeClientError(\n        'invalid_argument',\n        'Recipe JSON output requires --project-root.'\n      )\n    }\n    childArgs.push('--serve-recipe-json', '--serve-project-root', args.projectRoot)\n  }\n\n  const handoffPath =\n    args.recipeJson !== true && getMacAppBundlePath(executable)\n      ? getServeUpdateHandoffPath(getDefaultUserDataPath())\n      : null\n  const childEnv = stripElectronRunAsNode(process.env)\n  delete childEnv.ORCA_APPIMAGE_NO_SANDBOX\n  if (handoffPath) {\n    childEnv[SERVE_UPDATE_HANDOFF_PATH_ENV] = handoffPath\n  }\n  const spawnOptions: SpawnOptions = {\n    detached: args.recipeJson === true,","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/runtime/launch.ts#L93-L129","documentation":"Thrown by serveOrcaApp when `--recipe-json` (args.recipeJson) is requested but `--project-root` (args.projectRoot) is not provided. Recipe JSON output needs a project root to scope the served recipe, so the builder rejects the combination before constructing the child args. The check runs at serve-arg construction time.","triggerScenarios":"Invoking serve with `--serve-recipe-json` but no `--serve-project-root`, or programmatically calling serveOrcaApp({ recipeJson: true }) without projectRoot. Any path where args.recipeJson is true and args.projectRoot is falsy.","commonSituations":"Adopting recipe JSON output and forgetting the project-root flag. Scripts that conditionally enable recipeJson but leave projectRoot unset. Assuming the runtime infers the project root from cwd.","solutions":["Add `--serve-project-root /abs/path/to/project` alongside `--serve-recipe-json`.","If calling serveOrcaApp programmatically, pass `projectRoot` in the args object whenever `recipeJson` is true.","Drop `--serve-recipe-json` if you do not need recipe JSON output."],"exampleFix":"// before\nserveOrcaApp({ recipeJson: true })\n// after\nserveOrcaApp({ recipeJson: true, projectRoot: '/abs/path/to/project' })","handlingStrategy":"validation","validationCode":"if (serveArgs.recipeJson && !serveArgs.projectRoot) {\n  throw new Error('Recipe JSON output requires a project root')\n}","typeGuard":"function recipeRequestIsValid(args: { recipeJson?: boolean; projectRoot?: string | null }): boolean {\n  return !args.recipeJson || Boolean(args.projectRoot)\n}","tryCatchPattern":null,"preventionTips":["Always pair `--serve-recipe-json` with `--serve-project-root`.","In programmatic calls, set projectRoot whenever recipeJson is true."],"tags":["runtime","serve","flag-validation","recipe","project-root"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}