stablyai/orca · error · Error

codex app-server ${method} failed: ${response.error.message

Error message

codex app-server ${method} failed: ${response.error.message ?? 'unknown error'}

What it means

Thrown as a plain Error when a JSON-RPC response has an error that is NOT a method-not-found (code !== -32601 and message doesn't match 'method not found'). The codex app-server recognized the method but the call itself failed — an application-level error returned in response.error.message.

Source

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

      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)}` : ''}`
    )
  }

  try {

View on GitHub (pinned to 1136503c6a)

Solutions

Read response.error.message from the thrown string (after 'codex app-server <method> failed:') to classify.
For 'no rollout found', the rollout was deleted — healOneThread already maps this to 'missing'; let it record and continue.
For SQLITE_BUSY/LOCKED, abort the pass and retry on next startup when the other codex process releases the lock.
For config/batchWrite rejections, verify the keyPath (hooks.state.") and mergeStrategy ('upsert'/'replace') match this codex version's writer.
Check CODEX_HOME permissions and disk space.

Defensive patterns

Strategy: try-catch

Validate before calling

// For thread/read, pre-check the rollout file exists to avoid 'no rollout found':
if (!existsSync(expectedRolloutPath)) {
  // mark thread as missing without calling the RPC
}

Type guard

function isAppServerRpcFailure(error: unknown, method: string): boolean {
  return error instanceof Error && error.message.startsWith(`codex app-server ${method} failed:`)
}

Try / catch

try {
  await rpc.request(method, params)
} catch (error) {
  const msg = error instanceof Error ? error.message : String(error)
  if (/no rollout found/i.test(msg)) { /* record missing, continue */ }
  else if (/SQLITE_(?:BUSY|LOCKED)|database (?:is )?(?:busy|locked)/i.test(msg)) { /* abort batch, retry later */ }
  else { /* genuine failure: record or rethrow by policy */ }
}

Prevention

Parse response.error.message to classify missing vs locked vs genuine failure.
Abort and retry later on SQLITE_BUSY/LOCKED instead of burning the batch.
Verify config/batchWrite keyPath/mergeStrategy shapes against the codex version.
Ensure no concurrent codex process holds sqlite during heal.

When it happens

Trigger: thread/read failed because the rollout file is missing or corrupt ('no rollout found'); sqlite returned BUSY/LOCKED because another codex process owns the DB; config/batchWrite was rejected for a malformed edit; hooks/list failed on an unreadable hooks.json.

Common situations: A backfilled rollout was deleted after the audit was written; an active codex TUI holds sqlite; the hooks.state keyPath or value shape is wrong for this codex version; permissions on CODEX_HOME block the DB.

Related errors

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