stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Click modifiers accept modifier keys only, e.g. CmdOrCtrl or CmdOrCtrl+Shift.

What it means

On click, computerUseClickModifiersValidationMessage inspects --modifiers. It must be 1-4 parts joined by '+', each matching a known modifier after toLowerCase (alt, cmd, cmdorctrl, command, commandorcontrol, control, ctrl, meta, option, shift, super, win). Unlike hotkey, click modifiers do NOT strip spaces/underscores/hyphens, so 'Cmd Or Ctrl' fails. Non-modifier keys (e.g. a letter) and more than 4 parts also fail. The click target itself is supplied via --element-index or coordinates, not via --modifiers.

Source

Thrown at src/cli/handlers/computer-action-flags.ts:81

  mouseButton?: string
  modifiers?: string
} {
  const rawModifiers = flags.get('modifiers')
  const modifiers = typeof rawModifiers === 'string' ? rawModifiers : undefined
  const result = {
    elementIndex: getOptionalNonNegativeIntegerFlag(flags, 'element-index'),
    x: getOptionalNumberFlag(flags, 'x'),
    y: getOptionalNumberFlag(flags, 'y'),
    clickCount: getOptionalPositiveIntegerFlag(flags, 'click-count'),
    mouseButton: getOptionalStringFlag(flags, 'mouse-button'),
    modifiers
  }
  validateElementOrCoordinates('Click', result.elementIndex, result.x, result.y)
  validateMouseButton(result.mouseButton)
  if (modifiers !== undefined) {
    const message = computerUseClickModifiersValidationMessage(modifiers)
    if (message) {
      throw new RuntimeClientError('invalid_argument', message)
    }
  }
  return result
}

export function getComputerSecondaryActionFlags(flags: Map<string, string | boolean>): {
  elementIndex: number
  action: string
} {
  return {
    elementIndex: getRequiredNonNegativeIntegerFlag(flags, 'element-index'),
    action: getRequiredStringFlag(flags, 'action')
  }
}

export function getComputerScrollActionFlags(flags: Map<string, string | boolean>): {
  elementIndex?: number
  x?: number

View on GitHub (pinned to 1136503c6a)

Solutions

Use modifier names only, joined by +, e.g. --modifiers CmdOrCtrl+Shift
Drop --modifiers entirely if no modifier keys are needed
Remember the limit is 4 parts and case-insensitive but whitespace/underscores are not tolerated

Example fix

// before
orca computer click --app Safari --element-index 2 --modifiers Ctrl+A
// after
orca computer click --app Safari --element-index 2 --modifiers CmdOrCtrl+Shift

Defensive patterns

Strategy: validation

Validate before calling

import { computerUseClickModifiersValidationMessage } from '../../shared/computer-use-key-spec'
function assertClickModifiers(modifiers) {
  if (modifiers === undefined) return
  const message = computerUseClickModifiersValidationMessage(modifiers)
  if (message) throw new Error(message)
}

Prevention

Reuse the shared computerUseClickModifiersValidationMessage validator rather than reimplementing the rule
Remember click --modifiers holds modifier keys only; the pressed key goes through the element target, not here
Do not put spaces/underscores in modifier parts for click (hotkey tolerates them, click does not)

When it happens

Trigger: `--modifiers Ctrl+A` (A is not a modifier), `--modifiers Ctrl+Shift+Alt+Cmd+Win` (5 parts > 4), `--modifiers "Cmd Or"` (space not stripped), or an empty modifiers value.

Common situations: Putting the actual key into --modifiers instead of using hotkey; expecting hotkey-style normalization in click modifiers; pasting a hotkey string into --modifiers.

Related errors

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