{"record":{"id":"c2668a37bd490f93","repo":"stablyai/orca","slug":"serve-recipe-json-requires-serve-project-root","errorCode":null,"errorMessage":"--serve-recipe-json requires --serve-project-root","messagePattern":"--serve-recipe-json requires --serve-project-root","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/main/index.ts","lineNumber":1881,"sourceCode":"  const QRCode = await import('qrcode')\n  try {\n    return await QRCode.toString(pairingUrl, { type: 'terminal', small: true })\n  } catch {\n    try {\n      return await QRCode.toString(pairingUrl, { type: 'utf8' })\n    } catch {\n      return null\n    }\n  }\n}\n\nasync function printServeReady(options: ServeOptions): Promise<void> {\n  if (!runtime || !runtimeRpc) {\n    throw new Error('Runtime server must be initialized before printing serve readiness')\n  }\n  if (options.recipeJson) {\n    if (!options.projectRoot) {\n      throw new Error('--serve-recipe-json requires --serve-project-root')\n    }\n    if (!isAbsolute(options.projectRoot)) {\n      throw new Error(`--serve-project-root must be absolute: ${options.projectRoot}`)\n    }\n    const projectRootStats = statSync(options.projectRoot)\n    if (!projectRootStats.isDirectory()) {\n      throw new Error(`--serve-project-root must be a directory: ${options.projectRoot}`)\n    }\n  }\n  const boundEndpoint = runtimeRpc.getWebSocketEndpoint()\n  const advertised = boundEndpoint\n    ? resolveAdvertisedPairingEndpoint(boundEndpoint, options.pairingAddress)\n    : null\n  const pairing = options.noPairing\n    ? ({\n        available: false,\n        reason: 'disabled_by_operator',\n        guidance: 'Restart without --no-pairing to create a client pairing offer.'","sourceCodeStart":1863,"sourceCodeEnd":1899,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/index.ts#L1863-L1899","documentation":"Thrown by printServeReady when --serve-recipe-json is set but --serve-project-root was not supplied. Recipe JSON output needs a project root to scope the recipe, so the two flags are coupled: --serve-recipe-json makes --serve-project-root mandatory.","triggerScenarios":"Launching with `--serve-recipe-json` but omitting `--serve-project-root <abs-dir>`. The recipe path cannot be resolved without a project root, so readiness printing aborts.","commonSituations":"Partial flag copy-paste from docs/examples; a wrapper script that conditionally adds --serve-recipe-json but forgets the matching project-root argument; misunderstanding that the two flags are paired.","solutions":["Add --serve-project-root with an absolute directory path: `--serve-recipe-json --serve-project-root /abs/path/to/project`.","If you don't need recipe JSON output, remove --serve-recipe-json.","In wrapper scripts, set both flags together from a single variable."],"exampleFix":"// before\n--serve-recipe-json\n// after\n--serve-recipe-json --serve-project-root /home/me/projects/myapp","handlingStrategy":"validation","validationCode":"function validateServeFlags(argv: string[]): void {\n  const hasRecipe = argv.includes('--serve-recipe-json')\n  const hasRoot = argv.includes('--serve-project-root')\n  if (hasRecipe && !hasRoot) {\n    throw new Error('--serve-recipe-json requires --serve-project-root')\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat --serve-recipe-json and --serve-project-root as a paired set in wrapper scripts.","Add a CLI preflight assertion that checks both flags are supplied together.","Document the coupling prominently in serve-mode docs."],"tags":["cli","serve","recipe","args","configuration"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}