stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Recipe JSON output requires --project-root.

What it means

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.

Source

Thrown at src/cli/runtime/launch.ts:111

  childArgs.push('--serve')
  if (args.json) {
    childArgs.push('--serve-json')
  }
  if (args.port) {
    childArgs.push('--serve-port', args.port)
  }
  if (args.pairingAddress) {
    childArgs.push('--serve-pairing-address', args.pairingAddress)
  }
  if (args.noPairing) {
    childArgs.push('--serve-no-pairing')
  }
  if (args.mobilePairing) {
    childArgs.push('--serve-mobile-pairing')
  }
  if (args.recipeJson) {
    if (!args.projectRoot) {
      throw new RuntimeClientError(
        'invalid_argument',
        'Recipe JSON output requires --project-root.'
      )
    }
    childArgs.push('--serve-recipe-json', '--serve-project-root', args.projectRoot)
  }

  const handoffPath =
    args.recipeJson !== true && getMacAppBundlePath(executable)
      ? getServeUpdateHandoffPath(getDefaultUserDataPath())
      : null
  const childEnv = stripElectronRunAsNode(process.env)
  delete childEnv.ORCA_APPIMAGE_NO_SANDBOX
  if (handoffPath) {
    childEnv[SERVE_UPDATE_HANDOFF_PATH_ENV] = handoffPath
  }
  const spawnOptions: SpawnOptions = {
    detached: args.recipeJson === true,

View on GitHub (pinned to 1136503c6a)

Solutions

1. Add `--serve-project-root /abs/path/to/project` alongside `--serve-recipe-json`.
2. If calling serveOrcaApp programmatically, pass `projectRoot` in the args object whenever `recipeJson` is true.
3. Drop `--serve-recipe-json` if you do not need recipe JSON output.

Example fix

// before
serveOrcaApp({ recipeJson: true })
// after
serveOrcaApp({ recipeJson: true, projectRoot: '/abs/path/to/project' })

if (serveArgs.recipeJson && !serveArgs.projectRoot) {
  throw new Error('Recipe JSON output requires a project root')
}

function recipeRequestIsValid(args: { recipeJson?: boolean; projectRoot?: string | null }): boolean {
  return !args.recipeJson || Boolean(args.projectRoot)
}

When it happens

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

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

Related errors

• --serve-recipe-json requires --serve-project-root
• A fetch implementation is required.
• [verify-skills-cli-runtime] missing runtime import "${specif
• incompatible_runtime
• invalid_argument

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