What causes "${envelope.message}" in stablyai/orca?

Upgrade the codex CLI to a version that ships the app-server subcommand and the hooks RPCs.

stablyai/orca · warning · CodexAppServerUnsupportedError

${envelope.message}

Error message

${envelope.message}

What it means

Thrown as CodexAppServerUnsupportedError when the entry child returned a well-formed envelope with ok:false and unsupported:true. The unsupported flag is set by buildGrantEntryEnvelope only when the underlying error is a CodexAppServerUnsupportedError, meaning the spawned codex binary lacks the app-server subcommand or the specific RPC method (hooks/list, config/batchWrite). This is the typed, cacheable capability signal — the only error class the capability cache marks unsupported.

Source

Thrown at src/main/codex/codex-app-server-grant-bridge.ts:136

  const lastLine = lines.at(-1)
  let envelope: GrantEntryEnvelope | null = null
  if (lastLine) {
    try {
      envelope = JSON.parse(lastLine) as GrantEntryEnvelope
    } catch {
      envelope = null
    }
  }
  if (!envelope) {
    throw new Error(
      `codex trust-grant entry produced no result (exit ${spawned.status ?? 'unknown'})${
        spawned.stderr ? `: ${spawned.stderr.trim().slice(0, 400)}` : ''
      }`
    )
  }
  if (!envelope.ok) {
    if (envelope.unsupported) {
      throw new CodexAppServerUnsupportedError(envelope.message)
    }
    if (envelope.errorName === 'CodexAppServerTimeoutError') {
      throw new CodexAppServerTimeoutError(envelope.message)
    }
    throw new Error(envelope.message)
  }
  return envelope.result
}

View on GitHub (pinned to 1136503c6a)

Solutions

Upgrade the codex CLI to a version that ships the app-server subcommand and the hooks RPCs.
Confirm with: codex app-server --help (missing subcommand surfaces unsupported).
Let the capability cache record this result so repeated probes are suppressed — ensure isCodexAppServerUnsupportedError is the gate, not message matching.
If unsupported is expected and permanent for this host, keep the host on the managed-home lane (ensureRealHomeCodexHookState already falls back to 'unavailable').

Defensive patterns

Strategy: type-guard

Validate before calling

// Probe capability once before granting:
// codex app-server --help exit code / stderr tells you if the subcommand exists.
// Cache the result so repeated grants skip the probe.

Type guard

import { isCodexAppServerUnsupportedError } from './codex-app-server-session'
// isCodexAppServerUnsupportedError(error) === true for this error

Try / catch

try {
  runCodexHookTrustGrantSessionSync(request)
} catch (error) {
  if (isCodexAppServerUnsupportedError(error)) {
    // mark capability unsupported; stay on managed lane; do not retry eagerly
    capabilityCache.setUnsupported(host, 'app-server')
  } else {
    throw error
  }
}

Prevention

Gate real-home hook install on a cached capability probe so old CLIs never reach the grant.
Treat unsupported as permanent (retry interval = Infinity) per getInstallRetryAfterMs.
Surface a clear 'upgrade codex' message to the user when unsupported is first detected.
Re-probe only after a codex version bump, not on every launch.

When it happens

Trigger: The user's installed codex CLI predates the app-server subcommand; codex app-server exists but lacks hooks/list or config/batchWrite; the entry's runCodexAppServerSession classified an early exit as missing-subcommand via stderrIndicatesMissingAppServer and that bubbled up as unsupported through the envelope.

Common situations: User is on an old codex version; codex was installed via a package manager shipping a stale build; a CI environment pins an older codex; the capability cache was reset so the probe re-runs against an old binary.

Related errors

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