jdx/mise · error

checkpoint was written by a newer mise (schema )

Error message

checkpoint {} was written by a newer mise (schema {})

What it means

refuse_unusable validates a checkpoint entry before it can be replayed during a rollback. If the checkpoint was written by a mise whose history schema version is newer than this binary's SCHEMA_VERSION, replaying it is unsafe, so it refuses with this error rather than applying unknown data.

Solutions

1. Upgrade mise back to the version (or newer) that wrote the checkpoint so the schema is understood
2. If staying on the old version, start a fresh history store by pointing MISE_STATE_DIR at a new directory
3. Verify the checkpoint's schema with the newer mise before attempting rollback

Example fix

// before: old mise 2026.1.0 rolling back a schema-3 checkpoint
mise checkpoint rollback <id>
// after
mise upgrade   # then re-run the rollback
# or: export MISE_STATE_DIR=~/.local/state/mise-new

let meta = history.checkpoint_metadata(id)?;
if meta.schema_version > mise::history::store::SCHEMA_VERSION {
    eprintln!("checkpoint {id} needs newer mise (schema {})", meta.schema_version);
    return Ok(());
}

match history.rollback(id) {
    Err(e) if e.to_string().contains("written by a newer mise") => upgrade_mise_and_retry(id)?,
    other => other?,
}

When it happens

Trigger: Calling rollback on a checkpoint whose entry.checkpoint.schema_version exceeds super::store::SCHEMA_VERSION — i.e. the checkpoint was created by a newer mise build and the user downgraded or switched to an older mise binary.

Common situations: Downgrading mise (or switching to a release branch/older build) after newer versions recorded checkpoints in MISE_STATE_DIR; sharing one state dir between machines with different mise versions.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• cached rustc output directory has unsupported entries
• checkpoint did not finish; there is no state to roll back to
• unsupported remote cache client metadata version
• unsupported remote cache directory version
• a process it started kept its output open

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

Appendix: source

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

        if differs {
            return Ok(Some(entry.clone()));
        }
    }
    Ok(None)
}

fn refuse_unusable(entry: &Entry) -> Result<()> {
    if entry.checkpoint.status() == Some(OperationStatus::Pending) {
        bail!(
            "checkpoint {} did not finish; there is no state to roll back to",
            entry.id
        );
    }
    if entry.checkpoint.tree.snapshot.is_none() {
        bail!("checkpoint {} has no content snapshot", entry.id);
    }
    if entry.checkpoint.schema_version > super::store::SCHEMA_VERSION {
        bail!(
            "checkpoint {} was written by a newer mise (schema {})",
            entry.id,
            entry.checkpoint.schema_version
        );
    }
    Ok(())
}

/// Every path a checkpoint's coverage includes, as absolute paths.
fn covered_paths(checkpoint: &Checkpoint) -> Vec<PathBuf> {
    checkpoint
        .tree
        .coverage
        .entries
        .iter()
        .filter(|entry| entry.mode != "private")
        .map(|entry| normalize_target(Path::new(&entry.path)))
        .collect()

View on GitHub (pinned to 533346cc37)