{"record":{"id":"ef0993f8d204f269","repo":"stablyai/orca","slug":"peek-wait-unsupported","errorCode":"peek_wait_unsupported","errorMessage":"The connected runtime does not support --peek with --wait; upgrade the runtime or use --wait without --peek.","messagePattern":"The connected runtime does not support --peek with --wait; upgrade the runtime or use --wait without --peek\\.","errorType":"exception","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/handlers/orchestration.ts","lineNumber":665,"sourceCode":"        types: getOptionalStringFlag(flags, 'types'),\n        format: flags.has('format') ? true : undefined,\n        inject: flags.has('inject') ? true : undefined,\n        compatibilityCliCommand: resolveCompatibilityCliCommand(),\n        run: getOptionalStringFlag(flags, 'run'),\n        ack: getOptionalStringFlag(flags, 'ack'),\n        wait: wait ? true : undefined,\n        timeoutMs\n      })\n    } finally {\n      stopKeepalive?.()\n    }\n    if (peek) {\n      const rawRowCount = result.result.messages.length\n      const unreadOnly = result.result.messages.filter((m) => m.read !== 1)\n      const removedReadRows = unreadOnly.length !== rawRowCount\n      // Why: read rows mean a pre-peek runtime ran the all mode and returned instead of blocking; can't honor --wait, so fail loudly.\n      if (wait && removedReadRows && unreadOnly.length === 0) {\n        throw new RuntimeClientError(\n          'peek_wait_unsupported',\n          'The connected runtime does not support --peek with --wait; upgrade the runtime or use --wait without --peek.'\n        )\n      }\n      // Why: pre-peek runtimes cap the all mode at 100 rows; a full page may hide older unread — warn on stderr.\n      if (removedReadRows && rawRowCount >= 100) {\n        console.error(\n          'Warning: this runtime returned only its newest 100 messages for --peek; older unread messages may be missing. Upgrade the runtime for exact peek results.'\n        )\n      }\n      result = {\n        ...result,\n        result: {\n          ...result.result,\n          // Why: a pre-peek runtime builds `formatted` from all rows; drop it so output matches the filtered peek set.\n          ...(removedReadRows ? { formatted: undefined } : {}),\n          messages: unreadOnly,\n          count: unreadOnly.length","sourceCodeStart":647,"sourceCodeEnd":683,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/handlers/orchestration.ts#L647-L683","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Upgrade or restart the connected Orca runtime to a version that supports --peek.","Use '--wait' without '--peek' (mark-read unread mode) which older runtimes support.","Drop '--wait' and use '--peek' alone for a non-blocking snapshot."],"exampleFix":"// before\norca orchestration check --wait --peek   (against older runtime)\n// after\norca orchestration check --wait   # mark-read unread mode, runtime-compatible","handlingStrategy":"fallback","validationCode":"// Before combining --wait --peek, check the runtime advertises peek support.\nconst status = await client.call('status.get')\nconst supportsPeek = status.result.capabilities?.includes('orchestration.peek') // capability name per runtime\nif (!supportsPeek && wait && peek) {\n  // drop --peek or --wait before sending\n}","typeGuard":"function runtimeSupportsPeek(status: { result: { capabilities?: string[] } }): boolean {\n  return !!status.result.capabilities?.some((c) => c.includes('peek'))\n}","tryCatchPattern":"try {\n  await runCheck(['--wait','--peek'])\n} catch (err) {\n  if (err instanceof RuntimeClientError && err.code === 'peek_wait_unsupported') {\n    // downgrade: retry with '--wait' only (mark-read unread) or upgrade the runtime\n  } else { throw err }\n}","preventionTips":["Keep the CLI and runtime versions in sync.","When targeting mixed versions, prefer --wait without --peek for compatibility.","Check status.get capabilities before relying on newer flags."],"tags":["cli","orchestration","runtime-compat","version","peek"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}