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 refuses to roll back to a checkpoint whose schema_version is greater than the SCHEMA_VERSION the running mise supports. The checkpoint was written by a newer mise release, and its on-disk format may contain fields or semantics this binary cannot interpret safely.

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 afd2eddd3a)

Solutions

1. Upgrade mise to the version (or newer) that wrote the checkpoint, then retry rollback
2. If you must stay on the old mise, use a separate MISE_STATE_DIR so the incompatible history is not read
3. Abandon the rollback and manually restore the desired file state

Example fix

// before
MISE_STATE_DIR=~/.local/share/mise mise rollback  # old mise, new state
// after
mise upgrade && mise rollback  # or: MISE_STATE_DIR=~/.local/share/mise-new mise rollback

if entry.checkpoint.schema_version > store::SCHEMA_VERSION {
    eprintln!("checkpoint too new (schema {}); upgrade mise", entry.checkpoint.schema_version);
}

match rollback_result {
    Err(e) if e.to_string().contains("newer mise") => upgrade_mise_and_retry(),
    Err(e) => return Err(e),
    Ok(v) => v,
}

When it happens

Trigger: Running rollback in an older mise binary against history state written by a newer mise, i.e. entry.checkpoint.schema_version > super::store::SCHEMA_VERSION.

Common situations: Downgrading mise after using a newer version; switching between release and older installed builds sharing the same MISE_STATE_DIR; CI images pinned to an older mise version.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• task action manifest has an invalid identity
• unsupported local action result version
• unrecognized provenance table format in lockfile: {:?}
• expected a checkpoint
• no baseline

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