stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

--cursor must be a non-negative integer

What it means

Thrown by the `terminal read` handler when `--cursor` is supplied but does not match `/^\d+$/` (one or more digits, non-negative). The flag is optional; a missing cursor is fine. The error fires only when a value is present but isn't a pure digits string, so negative numbers, decimals, hex, and non-numeric text all fail.

Source

Thrown at src/cli/handlers/terminal.ts:77

      // Why: agent JSON calls dominate; topology stays available through an explicit opt-in.
      includeVisualLayouts: !json || flags.has('include-visual-layouts')
    })
    printResult(result, json, formatTerminalList)
  },
  'terminal show': async ({ flags, client, cwd, json }) => {
    const result = await client.call<{ terminal: RuntimeTerminalShow }>('terminal.show', {
      terminal: await getTerminalHandle(flags, cwd, client)
    })
    printResult(result, json, formatTerminalShow)
  },
  'terminal read': async ({ flags, client, cwd, json }) => {
    const cursorFlag = getOptionalStringFlag(flags, 'cursor')
    const cursor =
      cursorFlag !== undefined && /^\d+$/.test(cursorFlag)
        ? Number.parseInt(cursorFlag, 10)
        : undefined
    if (cursorFlag !== undefined && cursor === undefined) {
      throw new RuntimeClientError('invalid_argument', '--cursor must be a non-negative integer')
    }
    const result = await client.call<{ terminal: RuntimeTerminalRead }>('terminal.read', {
      terminal: await getTerminalHandle(flags, cwd, client),
      ...(cursor !== undefined ? { cursor } : {}),
      limit: getOptionalPositiveIntegerFlag(flags, 'limit')
    })
    printResult(result, json, formatTerminalRead)
  },
  'terminal send': async ({ flags, client, cwd, json }) => {
    const result = await client.call<{ send: RuntimeTerminalSend }>('terminal.send', {
      terminal: await getTerminalHandle(flags, cwd, client),
      text: getOptionalStringFlag(flags, 'text'),
      enter: flags.get('enter') === true,
      interrupt: flags.get('interrupt') === true,
      client: { id: 'orca-cli', type: 'desktop' }
    })
    printResult(result, json, formatTerminalSend)
  },

View on GitHub (pinned to 1136503c6a)

Solutions

1. Pass a non-negative integer of digits only, e.g. `--cursor 1024`.
2. Omit `--cursor` to read from the terminal's current/default position.
3. Sanitize variables: default to 0 or drop the flag when the value isn't pure digits.
4. For 'latest' content, omit cursor and use `--limit` to bound the read.

Example fix

// before
orca terminal read --cursor -1
orca terminal read --cursor 1.5
orca terminal read --cursor "$OFFSET"   // $OFFSET empty or non-numeric
// after
orca terminal read --cursor 1024
# script guard
[[ "$OFFSET" =~ ^[0-9]+$ ]] && args+=(--cursor "$OFFSET")

const cursorFlag = getOptionalStringFlag(flags, 'cursor')
if (cursorFlag !== undefined && !/^\d+$/.test(cursorFlag)) { /* reject before terminal.read */ }

function isNonNegativeIntegerString(v: string): boolean {
  return /^\d+$/.test(v)
}

try { await terminalRead(flags) }
catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'invalid_argument' && e.message === '--cursor must be a non-negative integer') {
    // coerce/derive a valid cursor (e.g. default to 0) or drop the flag and retry
  } else throw e
}

When it happens

Trigger: Running `orca terminal read --cursor <x>` with a negative number, a float, a hex value, a variable that expands to non-digits, or an expression like `--cursor end`.

Common situations: Passing a byte offset from a tool that emits negatives or floats; a shell variable that is empty/non-numeric; user assumes `end`/`tail` keywords are supported.

Related errors

• --trials must be a positive integer
• invalid_argument
• invalid_argument
• invalid_argument
• --higher-is-better requires a metric key

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