{"record":{"id":"47302d9ec53669d3","repo":"jdx/mise","slug":"checkpoint-was-written-by-a-newer-mise-schema","errorCode":null,"errorMessage":"checkpoint {} was written by a newer mise (schema {})","messagePattern":"checkpoint (.+?) was written by a newer mise \\(schema (.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/system/history/replay.rs","lineNumber":1486,"sourceCode":"        if differs {\n            return Ok(Some(entry.clone()));\n        }\n    }\n    Ok(None)\n}\n\nfn refuse_unusable(entry: &Entry) -> Result<()> {\n    if entry.checkpoint.status() == Some(OperationStatus::Pending) {\n        bail!(\n            \"checkpoint {} did not finish; there is no state to roll back to\",\n            entry.id\n        );\n    }\n    if entry.checkpoint.tree.snapshot.is_none() {\n        bail!(\"checkpoint {} has no content snapshot\", entry.id);\n    }\n    if entry.checkpoint.schema_version > super::store::SCHEMA_VERSION {\n        bail!(\n            \"checkpoint {} was written by a newer mise (schema {})\",\n            entry.id,\n            entry.checkpoint.schema_version\n        );\n    }\n    Ok(())\n}\n\n/// Every path a checkpoint's coverage includes, as absolute paths.\nfn covered_paths(checkpoint: &Checkpoint) -> Vec<PathBuf> {\n    checkpoint\n        .tree\n        .coverage\n        .entries\n        .iter()\n        .filter(|entry| entry.mode != \"private\")\n        .map(|entry| normalize_target(Path::new(&entry.path)))\n        .collect()","sourceCodeStart":1468,"sourceCodeEnd":1504,"githubUrl":"https://github.com/jdx/mise/blob/533346cc374382b41ec5ff70536252b2e96e725c/src/system/history/replay.rs#L1468-L1504","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade mise back to the version (or newer) that wrote the checkpoint so the schema is understood","If staying on the old version, start a fresh history store by pointing MISE_STATE_DIR at a new directory","Verify the checkpoint's schema with the newer mise before attempting rollback"],"exampleFix":"// before: old mise 2026.1.0 rolling back a schema-3 checkpoint\nmise checkpoint rollback <id>\n// after\nmise upgrade   # then re-run the rollback\n# or: export MISE_STATE_DIR=~/.local/state/mise-new","handlingStrategy":"validation","validationCode":"let meta = history.checkpoint_metadata(id)?;\nif meta.schema_version > mise::history::store::SCHEMA_VERSION {\n    eprintln!(\"checkpoint {id} needs newer mise (schema {})\", meta.schema_version);\n    return Ok(());\n}","typeGuard":null,"tryCatchPattern":"match history.rollback(id) {\n    Err(e) if e.to_string().contains(\"written by a newer mise\") => upgrade_mise_and_retry(id)?,\n    other => other?,\n}","preventionTips":["Keep mise up to date before sharing state dirs across machines","Pin one mise version per MISE_STATE_DIR","Check checkpoint schema before scripted rollbacks"],"tags":["versioning","schema","rollback","history"],"backgroundTag":"incompatible-source-type","analyzedSha":"533346cc374382b41ec5ff70536252b2e96e725c","analyzedAt":"2026-09-17T13:35:38.149Z","contentChangedAt":"2026-09-17T13:35:38.149Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}