incompatible monorepo lockfile formats; run `mise lock…

Error message

incompatible monorepo lockfile formats; run `mise lock --upgrade`

What it means

When reading the previous lockfile state for generation (`read_previous`, called from prepare_install), mise merges legacy monorepo subproject lockfiles into the root lockfile. If their lockfile_versions differ and `--upgrade` was not requested, the formats are incompatible for merging, so it stops and tells you to run `mise lock --upgrade` at the monorepo root, which permits taking the max version and migrating.

Solutions

Run `mise lock --upgrade` at the monorepo root to migrate all subproject lockfiles into the newer root format.
Remove/commit stale legacy subproject lockfiles so only the root lockfile remains.
Align the mise version (and lockfile format) across the team and CI, then regenerate and commit the root lockfile.

Example fix

// before
mise lock            # incompatible monorepo lockfile formats
// after
cd <monorepo-root>
mise lock --upgrade  # migrates legacy subproject lockfiles
git add mise.lock && git commit -m "chore: upgrade mise lockfile format"

Defensive patterns

Strategy: validation

Prevention

After any mise upgrade, run `mise lock --upgrade` at the monorepo root once and commit the result.
Delete legacy subproject mise.lock files once the monorepo root lockfile is in place.
Standardize the mise version in CI to match the one that wrote the lockfile format.

When it happens

Trigger: Running `mise lock` (or any command triggering prepare_install) in a monorepo where a legacy subproject lockfile with a different lockfile_version coexists with the root lockfile and no `--upgrade` flag was passed.

Common situations: Partially migrated monorepo after upgrading mise: some checkouts still carry old subproject lockfiles; merging branches where one regenerated the lockfile format; CI environments pinned to an older mise writing older-format lockfiles.

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

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

Appendix: source

Thrown at src/lockfile/generate.rs:155

}

pub(crate) fn read_previous(config: &Config, path: &Path, upgrade: bool) -> Result<Lockfile> {
    let mut previous = Lockfile::read(path)?;
    let mut exists = path.exists();
    for (source, target) in monorepo_lockfile_migration_paths(config) {
        if target != path || !source.exists() {
            continue;
        }
        let legacy = Lockfile::read(&source)?;
        if !exists {
            previous.lockfile_version = legacy.lockfile_version;
            previous
                .generated_header_url
                .clone_from(&legacy.generated_header_url);
            exists = true;
        } else if previous.lockfile_version != legacy.lockfile_version {
            if !upgrade {
                bail!("incompatible monorepo lockfile formats; run `mise lock --upgrade`");
            }
            previous.lockfile_version = previous.lockfile_version.max(legacy.lockfile_version);
        }
        merge_lockfile_preserving_root(&mut previous, legacy);
    }
    Ok(previous)
}

pub(crate) async fn prepare_install(config: &Arc<Config>, tv: &ToolVersion) -> Result<()> {
    let Some((path, _)) = lockfile_path_for_tool_source(config, tv.request.source()) else {
        return Ok(());
    };
    if !has_previous_file(config, &path)
        && (!config.lockfile_creation_enabled()
            || tv
                .request
                .source()
                .path()

View on GitHub (pinned to 533346cc37)