stablyai/orca · error · RuntimeClientError

peek_wait_unsupported

peek_wait_unsupported

Error message

The connected runtime does not support --peek with --wait; upgrade the runtime or use --wait without --peek.

What it means

Thrown in 'orchestration check' (line 665) during peek result post-processing when --wait and --peek are combined against a pre-peek (older) runtime. A pre-peek runtime ignores the peek field and falls back to the all mode, which returns immediately with read rows instead of blocking. The code detects this by comparing raw row count to the unread-filtered count (removedReadRows): if all returned rows were already read and the unread set is empty, the runtime could not honor a blocking peek, so it fails loudly rather than returning a misleading empty result.

Source

Thrown at src/cli/handlers/orchestration.ts:665

        types: getOptionalStringFlag(flags, 'types'),
        format: flags.has('format') ? true : undefined,
        inject: flags.has('inject') ? true : undefined,
        compatibilityCliCommand: resolveCompatibilityCliCommand(),
        run: getOptionalStringFlag(flags, 'run'),
        ack: getOptionalStringFlag(flags, 'ack'),
        wait: wait ? true : undefined,
        timeoutMs
      })
    } finally {
      stopKeepalive?.()
    }
    if (peek) {
      const rawRowCount = result.result.messages.length
      const unreadOnly = result.result.messages.filter((m) => m.read !== 1)
      const removedReadRows = unreadOnly.length !== rawRowCount
      // Why: read rows mean a pre-peek runtime ran the all mode and returned instead of blocking; can't honor --wait, so fail loudly.
      if (wait && removedReadRows && unreadOnly.length === 0) {
        throw new RuntimeClientError(
          'peek_wait_unsupported',
          'The connected runtime does not support --peek with --wait; upgrade the runtime or use --wait without --peek.'
        )
      }
      // Why: pre-peek runtimes cap the all mode at 100 rows; a full page may hide older unread — warn on stderr.
      if (removedReadRows && rawRowCount >= 100) {
        console.error(
          'Warning: this runtime returned only its newest 100 messages for --peek; older unread messages may be missing. Upgrade the runtime for exact peek results.'
        )
      }
      result = {
        ...result,
        result: {
          ...result.result,
          // Why: a pre-peek runtime builds `formatted` from all rows; drop it so output matches the filtered peek set.
          ...(removedReadRows ? { formatted: undefined } : {}),
          messages: unreadOnly,
          count: unreadOnly.length

View on GitHub (pinned to 1136503c6a)

Solutions

1. Upgrade or restart the connected Orca runtime to a version that supports --peek.
2. Use '--wait' without '--peek' (mark-read unread mode) which older runtimes support.
3. Drop '--wait' and use '--peek' alone for a non-blocking snapshot.

Example fix

// before
orca orchestration check --wait --peek   (against older runtime)
// after
orca orchestration check --wait   # mark-read unread mode, runtime-compatible

// Before combining --wait --peek, check the runtime advertises peek support.
const status = await client.call('status.get')
const supportsPeek = status.result.capabilities?.includes('orchestration.peek') // capability name per runtime
if (!supportsPeek && wait && peek) {
  // drop --peek or --wait before sending
}

function runtimeSupportsPeek(status: { result: { capabilities?: string[] } }): boolean {
  return !!status.result.capabilities?.some((c) => c.includes('peek'))
}

try {
  await runCheck(['--wait','--peek'])
} catch (err) {
  if (err instanceof RuntimeClientError && err.code === 'peek_wait_unsupported') {
    // downgrade: retry with '--wait' only (mark-read unread) or upgrade the runtime
  } else { throw err }
}

When it happens

Trigger: Calling 'orchestration check --wait --peek' against a runtime older than the peek feature, where the all-mode fallback returns only read messages and zero unread. Conditions at line 664 (wait && removedReadRows && unreadOnly.length === 0).

Common situations: Mixed client/runtime versions after an upgrade where the CLI is newer than the runtime; connecting to a remote Orca server that lags behind; CI against an older runtime image.

Related errors

• incompatible_runtime
• invalid_argument
• no_active_sender_terminal
• ${result.result.lifecycle.code}
• orchestration_migration_required

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