stablyai/orca · error

--serve-recipe-json requires --serve-project-root

Error message

--serve-recipe-json requires --serve-project-root

What it means

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.

Source

Thrown at src/main/index.ts:1881

  const QRCode = await import('qrcode')
  try {
    return await QRCode.toString(pairingUrl, { type: 'terminal', small: true })
  } catch {
    try {
      return await QRCode.toString(pairingUrl, { type: 'utf8' })
    } catch {
      return null
    }
  }
}

async function printServeReady(options: ServeOptions): Promise<void> {
  if (!runtime || !runtimeRpc) {
    throw new Error('Runtime server must be initialized before printing serve readiness')
  }
  if (options.recipeJson) {
    if (!options.projectRoot) {
      throw new Error('--serve-recipe-json requires --serve-project-root')
    }
    if (!isAbsolute(options.projectRoot)) {
      throw new Error(`--serve-project-root must be absolute: ${options.projectRoot}`)
    }
    const projectRootStats = statSync(options.projectRoot)
    if (!projectRootStats.isDirectory()) {
      throw new Error(`--serve-project-root must be a directory: ${options.projectRoot}`)
    }
  }
  const boundEndpoint = runtimeRpc.getWebSocketEndpoint()
  const advertised = boundEndpoint
    ? resolveAdvertisedPairingEndpoint(boundEndpoint, options.pairingAddress)
    : null
  const pairing = options.noPairing
    ? ({
        available: false,
        reason: 'disabled_by_operator',
        guidance: 'Restart without --no-pairing to create a client pairing offer.'

View on GitHub (pinned to 1136503c6a)

Solutions

1. Add --serve-project-root with an absolute directory path: `--serve-recipe-json --serve-project-root /abs/path/to/project`.
2. If you don't need recipe JSON output, remove --serve-recipe-json.
3. In wrapper scripts, set both flags together from a single variable.

Example fix

// before
--serve-recipe-json
// after
--serve-recipe-json --serve-project-root /home/me/projects/myapp

function validateServeFlags(argv: string[]): void {
  const hasRecipe = argv.includes('--serve-recipe-json')
  const hasRoot = argv.includes('--serve-project-root')
  if (hasRecipe && !hasRoot) {
    throw new Error('--serve-recipe-json requires --serve-project-root')
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid --serve-port value: ${rawPort}
• --serve-project-root must be absolute: ${options.projectRoot
• Unknown argument: ${arg}
• Missing value for ${flag}
• Usage: node config/scripts/release-rc-history.mjs <base-vers

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/c2668a37bd490f93. Report an issue: GitHub.