stablyai/orca · warning · CodexAppServerUnsupportedError

codex app-server does not support ${method}: ${response.erro

Error message

codex app-server does not support ${method}: ${response.error.message ?? 'method not found'}

What it means

Thrown as CodexAppServerUnsupportedError when a JSON-RPC response carries an error that is a method-not-found: code === -32601 (JSON_RPC_METHOD_NOT_FOUND) or a message matching /method not found/i. This means the codex binary's app-server supports the subcommand but not the specific method called (e.g., thread/read, hooks/list, config/batchWrite on an older build).

Source

Thrown at src/main/codex/codex-app-server-session.ts:254

      throw buildEarlyExitError()
    }
    const id = nextRequestId++
    const response = await new Promise<JsonRpcResponse>((resolve, reject) => {
      pending.set(id, { resolve, reject })
      const payload: Record<string, unknown> = { method, id }
      if (params !== undefined) {
        payload.params = params
      }
      try {
        sendLine(payload)
      } catch (error) {
        pending.delete(id)
        reject(error instanceof Error ? error : new Error(String(error)))
      }
    })
    if (response.error) {
      if (isMethodNotFoundError(response.error)) {
        throw new CodexAppServerUnsupportedError(
          `codex app-server does not support ${method}: ${response.error.message ?? 'method not found'}`
        )
      }
      throw new Error(
        `codex app-server ${method} failed: ${response.error.message ?? 'unknown error'}`
      )
    }
    return response.result
  }

  function buildEarlyExitError(): Error {
    if (stderrIndicatesMissingAppServer(stderrTail)) {
      return new CodexAppServerUnsupportedError(
        `codex CLI does not support the app-server subcommand: ${stderrTail.trim().slice(0, 400)}`
      )
    }
    return new Error(
      `codex app-server exited before completing the session${stderrTail ? `: ${stderrTail.trim().slice(0, 400)}` : ''}`

View on GitHub (pinned to 1136503c6a)

Solutions

Upgrade codex to a version that implements the method (check codex's app-server RPC changelog).
Gate the call behind a capability check / isCodexAppServerUnsupportedError so older hosts degrade instead of throwing.
For heal, the pass already records 'unsupported' and re-probes later — ensure shouldStop and the unsupported marker path are honored.
Confirm the method name is current; codex may have renamed it.

Defensive patterns

Strategy: type-guard

Validate before calling

// Cache per-host, per-method capability so unsupported methods are probed once:
if (capabilityCache.isUnsupported(host, method)) {
  // skip the call; degrade gracefully
}

Type guard

import { isCodexAppServerUnsupportedError } from './codex-app-server-session'
// For method-not-found, the thrown error is CodexAppServerUnsupportedError with
// message starting 'codex app-server does not support <method>:'

Try / catch

try {
  await rpc.request('thread/read', { threadId })
} catch (error) {
  if (isCodexAppServerUnsupportedError(error)) {
    capabilityCache.setUnsupported(host, 'thread/read')
    // record heal marker as unsupported; stop probing this host
  } else {
    throw error
  }
}

Prevention

Gate RPC calls behind a per-host capability cache keyed by method name.
Treat method-not-found as permanent for that codex version; re-probe only after an upgrade.
Upgrade codex to a build that implements the methods you call.
Use isCodexAppServerUnsupportedError (not message matching) to classify.

When it happens

Trigger: Calling thread/read on a codex build that predates lazy thread indexing; calling hooks/list before that RPC was added; calling config/batchWrite on a version that only supported direct config writes; the method name was renamed/removed in a codex release.

Common situations: Index-heal runs thread/read against an older codex; the grant client calls hooks/list on a codex that lacks the hooks RPC surface; a point-release dropped or gated an RPC.

Related errors

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