stablyai/orca · error

Invalid --serve-port value

Error message

Invalid --serve-port value: ${rawPort}

What it means

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.

Solutions

1. Supply an integer port in [0, 65535], e.g. `--serve-port 8787`.
2. If the port comes from an env var, validate it in the launching script before forwarding to --serve-port.
3. For ephemeral binding, pick 0 (the OS assigns a free port).

Example fix

// before
const parsedPort = Number(rawPort)
if (!Number.isInteger(parsedPort) || parsedPort < 0 || parsedPort > 65535) {
  throw new Error(`Invalid --serve-port value: ${rawPort}`)
}
// after — clearer error naming the constraint
const parsedPort = Number(rawPort)
if (!Number.isInteger(parsedPort) || parsedPort < 0 || parsedPort > 65535) {
  throw new Error(`Invalid --serve-port value: ${rawPort}. Must be an integer in [0, 65535].`)
}

function isValidPort(value: string): boolean {
  const n = Number(value)
  return Number.isInteger(n) && n >= 0 && n <= 65535
}

function isValidServePort(rawPort: unknown): rawPort is string {
  return typeof rawPort === 'string' && /^\d+$/.test(rawPort)
    && Number.isInteger(Number(rawPort)) && Number(rawPort) >= 0 && Number(rawPort) <= 65535
}

When it happens

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

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

Related errors

• --serve-project-root must be absolute
• invalid_argument
• Missing value for
• --serve-project-root must be a directory
• --serve-recipe-json requires --serve-project-root

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

Appendix: source

Thrown at src/main/index.ts:1835

  recipeJson: boolean
  projectRoot: string | null
}

function getServeOptions(argv = process.argv): ServeOptions {
  const valueAfter = (flag: string): string | null => {
    const index = argv.indexOf(flag)
    if (index === -1) {
      return null
    }
    const value = argv[index + 1]
    return value && !value.startsWith('--') ? value : null
  }
  const rawPort = valueAfter('--serve-port')
  let wsPort: number | undefined
  if (rawPort) {
    const parsedPort = Number(rawPort)
    if (!Number.isInteger(parsedPort) || parsedPort < 0 || parsedPort > 65535) {
      throw new Error(`Invalid --serve-port value: ${rawPort}`)
    }
    wsPort = parsedPort
  }
  return {
    json: argv.includes('--serve-json'),
    ...(wsPort !== undefined ? { wsPort } : {}),
    pairingAddress: valueAfter('--serve-pairing-address'),
    noPairing: argv.includes('--serve-no-pairing'),
    mobilePairing: argv.includes('--serve-mobile-pairing'),
    recipeJson: argv.includes('--serve-recipe-json'),
    projectRoot: valueAfter('--serve-project-root')
  }
}

function getBundledWebClientRoot(): string | undefined {
  const appPath = app.getAppPath()
  const roots = [
    join(appPath, 'out', 'web'),

View on GitHub (pinned to 1136503c6a)