stablyai/orca · warning · Error

Terminal checkpoint replay is unavailable

Error message

Terminal checkpoint replay is unavailable

What it means

Thrown during checkpoint serialization fallback: the direct bounded JSON stringification exceeded the byte limit, so the serializer tries to replay the snapshot through a headless emulator to trim it. If ColdRestoreReplayWriter.write() returns false for any ANSI segment (scrollbackAnsi, rehydrateSequences, snapshotAnsi, pendingEscapeTailAnsi), the emulator could not replay it (e.g., exceeded operation/char budgets or rejected the input) and replay is unavailable.

Source

Thrown at src/main/daemon/terminal-checkpoint-serializer.ts:232

  return writer.result()
}

async function replaySnapshot(snapshot: TerminalSnapshot): Promise<HeadlessEmulator> {
  const emulator = new HeadlessEmulator({
    cols: snapshot.cols,
    rows: snapshot.rows,
    scrollback: Math.max(0, Math.min(50_000, snapshot.scrollbackLines))
  })
  const replay = new ColdRestoreReplayWriter(emulator)
  try {
    for (const segment of [
      snapshot.scrollbackAnsi,
      snapshot.rehydrateSequences,
      snapshot.snapshotAnsi,
      snapshot.pendingEscapeTailAnsi ?? ''
    ]) {
      if (!(await replay.write(segment))) {
        throw new Error('Terminal checkpoint replay is unavailable')
      }
    }
    emulator.setCwd(snapshot.cwd)
    if (snapshot.lastTitle) {
      emulator.setLastTitle(snapshot.lastTitle)
    }
    emulator.setRestoredOscLinks(snapshot.oscLinks)
    return emulator
  } catch (error) {
    emulator.dispose()
    throw error
  }
}

export async function serializeTerminalCheckpointWithinLimit(
  snapshot: TerminalSnapshot,
  metadata: CheckpointMetadata,
  maxBytes: number

View on GitHub (pinned to 1136503c6a)

Solutions

1. Let the caller treat checkpoint serialization as best-effort: catch the error and skip persisting this checkpoint rather than crashing.
2. Investigate the snapshot source if replay consistently fails (capture a cleaner snapshot with less scrollback).
3. Reduce the snapshot size before serialization (cap scrollbackRows at capture time).
4. Ensure the headless emulator's writeSync budget is not being exhausted by pathological escape sequences.

function isCheckpointReplayUnavailable(e: unknown): boolean {
  return e instanceof Error && e.message === 'Terminal checkpoint replay is unavailable'
}

try {
  return await serializeTerminalCheckpointWithinLimit(snapshot, metadata, maxBytes)
} catch (e) {
  if (e instanceof Error && e.message === 'Terminal checkpoint replay is unavailable') {
    // skip persisting this checkpoint; history is best-effort
    return null
  }
  throw e
}

When it happens

Trigger: serializeTerminalCheckpointWithinLimit falls back to replaySnapshot, and emulator.writeSync returns false during replay of one of the four ANSI segments — typically because the segment is malformed, oversized, or trips the per-turn operation budget.

Common situations: A snapshot with extremely large or corrupt scrollback ANSI; a snapshot captured from an emulator whose escape sequences the headless replay cannot reproduce; a checkpoint just over the byte limit whose trimmed replay still fails.

Related errors

• ${tag} does not contain ${name}
• Failed to load commit history
• terminal_history_recovery_protected
• terminal_history_recovery_generation_changed
• NDJSON line exceeds max ${maxLineBytes} bytes (${lineBytes}

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