What causes "no history checkpoint matches {spec:?}" in jdx/mise?

Run `mise dot log` to list current checkpoints and verify the prefix exists.

no history checkpoint matches {spec:?}

Error message

no history checkpoint matches {spec:?}

What it means

Checkpoint references are matched by UUID prefix against the stored history entries. If no entry's checkpoint UUID starts with the given prefix, the reference names nothing in the current history and this error is thrown, echoing the spec so the user can see what was searched. The history may have been rewritten, or the prefix may be a typo.

Source

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

        })?;
        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 afd2eddd3a)

Solutions

Run `mise dot log` to list current checkpoints and verify the prefix exists.
Copy the checkpoint ID fresh from the log output instead of from notes/history.
If the history was reset, re-create the state you want and make a new checkpoint.
Check you're operating in the correct project/store directory.

Example fix

// before
let id = resolve_checkpoint("a1b2")?; // no match
// after: resolve from live listing
let spec = list_checkpoints()?.first().checkpoint.uuid[..6].to_string();
let id = resolve_checkpoint(&spec)?;

Defensive patterns

Strategy: validation

Validate before calling

let known: Vec<String> = list_checkpoints()?.iter().map(|c| c.checkpoint.uuid.clone()).collect();
if !known.iter().any(|u| u.starts_with(prefix)) {
    eprintln!("prefix {prefix:?} matches nothing; see `mise dot log`");
}

Try / catch

match resolve_checkpoint(spec) {
    Ok(id) => use(id),
    Err(e) if e.to_string().contains("no history checkpoint matches") => {
        eprintln!("unknown checkpoint; list current ones with `mise dot log`");
    }
    Err(e) => return Err(e),
}

Prevention

Re-copy checkpoint IDs from `mise dot log` after any history reset
Double-check UUID characters when typing prefixes
Confirm you're in the correct project/store before referencing checkpoints

When it happens

Trigger: Calling the checkpoint-resolution API with a UUID prefix that matches zero entries — stale ID from a previous history, typo, or a full ID from a checkpoint that no longer exists after a history reset.

Common situations: Restoring a checkpoint recorded before a `mise dot` history reset or machine migration; mis-typing a UUID character; referencing a checkpoint from a different project's store.

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@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/cb248c0ea2a49c64. Report an issue: GitHub.