checkpoint is unavailable; cannot find the state before…

Error message

checkpoint {} is unavailable; cannot find the state before operation {}

What it means

The operation references a protective 'before' checkpoint by UUID, but that checkpoint is not present in the loaded history entries. Without the snapshot's contents, undo cannot reconstruct pre-operation state and aborts.

Solutions

Restore the missing checkpoint in the history store (e.g. from a backup of the dotfiles git repo) and retry undo
Manually restore the affected files from your own backup, then let a fresh checkpoint re-baseline state
Prune the dangling operation from history so undo no longer resolves to it

Defensive patterns

Strategy: fallback

Validate before calling

const before = entries.find(e => e.checkpoint.uuid === op.before);
if (!before) throw new Error('referenced before-checkpoint missing from history');

Try / catch

try {
  await mise.dot.undo();
} catch (e) {
  if (/is unavailable/.test(e.message)) {
    // restore from external backup or prune the dangling entry
  }
}

Prevention

Do not delete or truncate the dotfiles history store
Back up history before retention pruning or migration
Keep history on one machine or migrate it fully

When it happens

Trigger: `entries.iter().find(|e| e.checkpoint.uuid == before_uuid)` returns `None` during undo — the referenced checkpoint was pruned, the history store was reset/reinitialized, or history was copied between machines losing entries.

Common situations: User manually cleaned or truncated the dotfiles history git store; history retention settings pruned old checkpoints; switching machines while referencing old operation ids.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/c0e02479b92a3ace. Report an issue: GitHub.

Appendix: source

Thrown at src/system/history/replay.rs:299

    if op.status == OperationStatus::Failed && !op.affected.is_empty() {
        info!(
            "history: operation {} failed midway; reversing the {} path(s) it changed",
            operation.id,
            op.affected.len()
        );
    }
    let Some(before_uuid) = &op.before else {
        bail!(
            "checkpoint {} has no protective checkpoint to undo from",
            operation.id
        );
    };
    let Some(before) = entries
        .iter()
        .find(|entry| &entry.checkpoint.uuid == before_uuid)
        .cloned()
    else {
        bail!(
            "checkpoint {} is unavailable; cannot find the state before operation {}",
            before_uuid,
            operation.id
        );
    };
    if op.affected.is_empty() {
        info!("history: operation {} touched nothing", operation.id);
        return Ok(());
    }
    let paths: Vec<PathBuf> = op
        .affected
        .iter()
        .map(|path| normalize_target(Path::new(path)))
        .collect();
    let message = format!(
        "undid {} {} ({})",
        op.kind.as_str(),
        operation.id,

View on GitHub (pinned to 533346cc37)