stablyai/orca · error · Error

Failed to persist Codex session index-heal outcome for ${thr

Error message

Failed to persist Codex session index-heal outcome for ${thread.threadId}

What it means

Thrown when appendHealLedgerRecord returned false for a thread's heal outcome — the JSONL append to the heal ledger (healLedgerPath) failed. Recording the outcome is critical: without it, a healed thread would be re-healed forever, and a failed one would never be retried. So a failed append aborts healOneThread rather than silently losing the record.

Source

Thrown at src/main/codex/codex-session-index-heal.ts:250

      return
    }
    if (/SQLITE_(?:BUSY|LOCKED)|database (?:is )?(?:busy|locked)/i.test(message)) {
      // Why: an active Codex process can briefly own sqlite; leave the id off
      // the ledger and abort this pass so a later startup resumes it.
      throw error
    }
    summary.failedThreads += 1
    recordHealOutcome(paths, thread, 'failed')
  }
}

function recordHealOutcome(
  paths: CodexSessionIndexHealPaths,
  thread: PendingHealThread,
  outcome: HealLedgerOutcome
): void {
  if (!appendHealLedgerRecord(paths, thread.threadId, outcome, thread.auditRecordId)) {
    throw new Error(`Failed to persist Codex session index-heal outcome for ${thread.threadId}`)
  }
}

function resolveHealWorkLimit(value: number | undefined, maximum: number): number {
  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
    return maximum
  }
  return Math.min(Math.floor(value), maximum)
}

function buildNativeHealInvocation(
  systemCodexHomePath: string,
  timeoutMs: number
): CodexAppServerInvocation {
  const command = resolveCodexCommand()
  const { spawnCmd, spawnArgs } = getSpawnArgsForWindows(command, ['app-server'])
  return {
    command: spawnCmd,

View on GitHub (pinned to 1136503c6a)

Solutions

Check write permissions on dirname(paths.healLedgerPath).
Free disk space.
Ensure the Orca state directory persists across the run (not a tmpdir that was cleared).
On Windows, exclude the Orca state dir from antivirus locking.
If the ledger is corrupt, back it up and remove it so the next pass rebuilds from the audit log.

Defensive patterns

Strategy: try-catch

Validate before calling

import { access, constants } from 'node:fs/promises'
import { dirname } from 'node:path'
try {
  await access(dirname(paths.healLedgerPath), constants.W_OK)
} catch {
  // ledger dir not writable; skip this heal pass rather than aborting per-thread
}

Type guard

function isHealLedgerPersistError(error: unknown): boolean {
  return error instanceof Error && error.message.startsWith('Failed to persist Codex session index-heal outcome for ')
}

Try / catch

try {
  recordHealOutcome(paths, thread, outcome)
} catch (error) {
  if (isHealLedgerPersistError(error)) {
    // abort this heal pass; the thread stays off the ledger and retries next pass
    summary.outcome = 'aborted'
  } else throw error
}

Prevention

Keep the Orca state directory writable and on a stable mount.
Ensure disk space during large heal passes.
Exclude the state dir from antivirus locking on Windows.
A failed append leaves the thread unrecorded; it retries on the next startup automatically.

When it happens

Trigger: The heal ledger file is not writable (permissions, read-only mount); the parent directory was removed; disk is full so the append can't flush; the ledger write hit an OS error that appendHealLedgerRecord swallows and returns false for.

Common situations: Orca state directory permissions changed mid-run; disk filled during a large heal pass; the state dir is on a network mount that dropped; an antivirus quarantined the ledger file.

Related errors

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