jdx/mise · error

cannot merge lockfile version

Error message

cannot merge lockfile version {} from {} into lockfile version {} at {}; run `mise lock --upgrade` at the monorepo root

What it means

When mise merges a subproject (legacy) lockfile into the monorepo root lockfile, the two files must use the same lockfile_version unless format upgrades are allowed for this operation. Hitting this branch means the root and subproject versions differ and `allow_format_upgrade` was false, so mise refuses to guess which format to keep and directs you to run `mise lock --upgrade` at the monorepo root, which enables upgrade mode.

Solutions

1. Run `mise lock --upgrade` at the monorepo root to migrate all subproject lockfiles into the root with the newer format.
2. Delete or commit/regenerate stale subproject lockfiles so root and subproject versions agree.
3. After upgrading, commit the regenerated root lockfile so teammates get matching formats.

Example fix

// before: plain install hits the version mismatch
mise install
// after: upgrade formats at the root first
cd <monorepo-root> && mise lock --upgrade && mise install

When it happens

Trigger: Running ordinary commands (install/exec, non-upgrade migration paths) while a subproject `mise.lock` with a different lockfile_version than the root lockfile exists and needs migrating into the root; committing a new-format root lockfile while a teammate still has an old-format subproject lockfile on disk.

Common situations: Mixed-version team after a mise upgrade: one machine regenerated the lockfile in the new format, another checkout still has version-0/old subproject lockfiles; branch merges that combine old and new lockfiles; stale subproject lockfiles left behind after switching to monorepo-root locking.

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

• incompatible monorepo lockfile formats; run `mise lock…
• npm: dependency graph does not match root version ; run…
• additional_artifacts must be an array in lockfile
• affected project exists in graph
• aube lockfile mapping keys must be strings

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

Appendix: source

Thrown at src/lockfile.rs:2231

            Lockfile::read(target).unwrap_or_else(|err| handle_lockfile_read_error(err, target));
        let subproject_lockfile = match Lockfile::read(source) {
            Ok(lockfile) => lockfile,
            Err(err) if is_not_found_report(&err) => continue,
            Err(err) => return Err(err),
        };
        if !target_existed {
            root_lockfile.lockfile_version = subproject_lockfile.lockfile_version;
        } else if root_lockfile.lockfile_version != subproject_lockfile.lockfile_version
            && allow_format_upgrade
        {
            // Keep the newer format so request bindings from either input remain
            // serialized if the subsequent rebuild fails. Entries imported from
            // version 0 remain reachable through the unbound-entry fallback.
            root_lockfile.lockfile_version = root_lockfile
                .lockfile_version
                .max(subproject_lockfile.lockfile_version);
        } else if root_lockfile.lockfile_version != subproject_lockfile.lockfile_version {
            bail!(
                "cannot merge lockfile version {} from {} into lockfile version {} at {}; run `mise lock --upgrade` at the monorepo root",
                subproject_lockfile.lockfile_version,
                display_path(source),
                root_lockfile.lockfile_version,
                display_path(target)
            );
        }
        merge_lockfile_preserving_root(&mut root_lockfile, subproject_lockfile);
        root_lockfile.save(target)?;
        if let Err(err) = fs::remove_file(source)
            && err.kind() != ErrorKind::NotFound
        {
            return Err(err.into());
        }
        remove_migrated_sidecars(source, target)?;
        migrated += 1;
    }

View on GitHub (pinned to 533346cc37)