stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

--${name} must be between 0 and 1

What it means

Thrown by assertNormalizedCoordinate in emulator.ts when an emulator gesture coordinate (x or y) falls outside the normalized [0,1] range. Emulator touch/gesture points use normalized coordinates relative to the device viewport, so any value below 0 or above 1 is rejected as invalid_argument before being sent to the emulator backend. The function is reused for both x and y of every parsed gesture point.

Source

Thrown at src/cli/handlers/emulator.ts:59

  state?: string
}

function formatEmulatorDevices(value: unknown): string {
  const devices = Array.isArray(value) ? (value as EmulatorDeviceRow[]) : []
  if (devices.length === 0) {
    return 'No emulator devices found.'
  }
  return devices
    .map((device) => {
      const platform = device.backend === 'android' ? 'Android' : 'iOS'
      return `${platform.padEnd(8)} ${(device.state ?? '').padEnd(9)} ${device.name ?? ''}  (${device.id ?? ''})`
    })
    .join('\n')
}

function assertNormalizedCoordinate(value: number, name: string): void {
  if (value < 0 || value > 1) {
    throw new RuntimeClientError('invalid_argument', `--${name} must be between 0 and 1`)
  }
}

function parseEmulatorGesturePoints(raw: string): EmulatorGesturePoint[] {
  let parsed: unknown
  try {
    parsed = JSON.parse(raw)
  } catch {
    throw new RuntimeClientError('invalid_argument', '--points must be valid JSON')
  }
  const value =
    parsed && typeof parsed === 'object' && 'points' in parsed
      ? (parsed as { points?: unknown }).points
      : parsed
  if (!Array.isArray(value) || value.length < 2 || value.length > 64) {
    throw new RuntimeClientError(
      'invalid_argument',
      '--points must be an array of 2 to 64 touch points'

View on GitHub (pinned to 1136503c6a)

Solutions

1. Recompute the coordinate as (pixel_offset / screen_dimension) so it falls within [0,1].
2. If you have absolute pixels, divide x by device width and y by device height before building the --points JSON.
3. Validate the points array with a quick script that asserts every x and y is between 0 and 1 inclusive.

Example fix

// before
--points '[{"type":"begin","x":540,"y":1200}]'
// after (assuming 1080x2400 screen)
--points '[{"type":"begin","x":0.5,"y":0.5}]'

function isValidNormalized(n: number): boolean {
  return typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= 1;
}
const allCoordsValid = points.every(p => isValidNormalized(p.x) && isValidNormalized(p.y));

function isNormalizedCoordinate(value: unknown): value is number {
  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
}

When it happens

Trigger: Passing --points with an x or y value like 1.5, -0.2, or 2; calling emulator gesture/swipe commands whose JSON includes out-of-range coordinates. The check fires after per-point numeric validation, inside parseEmulatorGesturePoints via assertNormalizedCoordinate(x, `points[${index}].x`).

Common situations: Authoring gesture JSON with pixel coordinates instead of normalized fractions; assuming the coordinate system is 0..100 or 0..screen-width; copying coordinates from a tool that uses a different normalization.

Related errors

• invalid_argument
• emulator_no_active
• --higher-is-better requires a metric key
• Usage: node config/scripts/compare-benchmark-artifacts.mjs -
• --baseline requires a path

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