jdx/mise · error

no history checkpoint matches

Error message

no history checkpoint matches {spec:?}

What it means

Checkpoint references may be given as a UUID prefix; mise filters the stored checkpoints by `starts_with(prefix)`. If no checkpoint's UUID begins with the given prefix, nothing matches and mise reports the spec with its debug formatting so the user can see exactly what was searched. It means the requested history entry does not exist.

Solutions

1. List checkpoints (`mise dotfiles history list`) and copy an exact id.
2. Re-run with a longer or corrected prefix if you only remember part of it.
3. If the checkpoint was pruned by retention policy, restore from backup or accept it is gone.
4. Confirm you are operating on the same history store/machine where the checkpoint was made.

Example fix

// before
mise dotfiles show deadbeef
Error: no history checkpoint matches "deadbeef"

// after
mise dotfiles history list   # find a valid id
mise dotfiles show <valid-id>

let ids = list_checkpoint_ids()?; // from `history list`
if !ids.iter().any(|id| id.starts_with(prefix)) {
  eprintln!("prefix {prefix} matches no checkpoint");
}

fn prefix_exists(prefix: &str, entries: &[Entry]) -> bool {
  entries.iter().any(|e| e.checkpoint.uuid.starts_with(prefix))
}

When it happens

Trigger: Referencing a checkpoint by an id/prefix that was never created, was pruned by retention, or was created in a different history store; typo in the prefix (e.g. `0` instead of `O`).

Common situations: Typo'd or truncated id pasted from docs; history cleaned up between sessions; referencing a checkpoint from another machine or profile.

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

• invalid checkpoint reference
• matches more than one checkpoint; use a longer prefix
• appeared after was protected; nothing more was changed
• cannot encode # as JSON
• cannot retain an unreadable plaintext version of newly…

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

Appendix: source

Thrown at src/system/history/store.rs:1018

        })?;
        return entries
            .iter()
            .find(|entry| entry.id == id)
            .map(|entry| entry.id)
            .ok_or_else(|| eyre!("no history checkpoint matches {spec:?}"));
    } else {
        spec
    };
    if prefix.is_empty() {
        bail!("invalid checkpoint reference {spec:?}");
    }
    let matches: Vec<&Entry> = entries
        .iter()
        .filter(|entry| entry.checkpoint.uuid.starts_with(prefix))
        .collect();
    match matches.as_slice() {
        [one] => Ok(one.id),
        [] => bail!("no history checkpoint matches {spec:?}"),
        _ => bail!("{spec:?} matches more than one checkpoint; use a longer prefix"),
    }
}

pub(crate) fn now_rfc3339() -> String {
    chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Millis, true)
}

pub(crate) fn new_uuid() -> String {
    uuid::Uuid::now_v7().to_string()
}

pub(crate) fn write_json<T: Serialize>(path: &Path, value: &T) -> Result<()> {
    let mut text = serde_json::to_string_pretty(value)?;
    text.push('\n');
    if let Some(parent) = path.parent() {
        file::create_dir_all(parent)?;
    }

View on GitHub (pinned to 533346cc37)