unsupported lockfile version

Error message

unsupported lockfile version {lockfile_version}; this mise supports up to version {CURRENT_LOCKFILE_VERSION}

What it means

mise.lock starts with `lockfile_version`. If that integer is greater than the CURRENT_LOCKFILE_VERSION compiled into the running mise, the parser refuses to read it, because it cannot safely interpret a future format (fields may be missing, renamed, or reinterpreted).

Solutions

Upgrade mise to the latest release so it supports the lockfile's version.
If upgrading isn't possible, delete mise.lock (or remove the lockfile_version constraint understanding) and re-lock with the current mise via `mise lock`.
Align team/CI mise versions (e.g. pin mise itself via mise.lock bootstrap or CI setup) to avoid version skew.

Example fix

# before: lockfile_version = 3 written by newer mise, local mise supports 2

# after: upgrade mise, or regenerate
$ mise upgrade mise
$ mise lock

Defensive patterns

Strategy: fallback

Validate before calling

const ver = doc.get('lockfile_version') ?? 0;
if (ver > CURRENT_LOCKFILE_VERSION) throw new Error(`lockfile_version ${ver} exceeds supported ${CURRENT_LOCKFILE_VERSION}; upgrade mise`);

Try / catch

try {
  mise('install');
} catch (e) {
  if (String(e).includes('unsupported lockfile version')) {
    upgradeMise(); // e.g. mise self-update or package-manager update
  } else { throw e; }
}

Prevention

Pin and auto-update mise in CI images.
Upgrade mise before pulling lockfile changes from teammates.
Never manually bump lockfile_version.
Document the mise version requirement in the repo (e.g. mise enrs or README).

When it happens

Trigger: Running `mise install`/`mise lock`/any lockfile-reading command in a mise binary older than the one that wrote the lockfile (higher lockfile_version), or manually bumping lockfile_version in mise.lock.

Common situations: Checking out a project whose lockfile was written by a teammate on a newer mise; using an outdated mise on CI; hand-editing lockfile_version upward.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at src/lockfile.rs:1198

        }
        trace!("reading lockfile {}", path.display_user());
        // Sidecars belong to the lockfile target, including when only the
        // lockfile (and not its sidecar files) has been symlinked elsewhere.
        let target = path
            .is_symlink()
            .then(|| fs::canonicalize(path))
            .transpose()?;
        let path = target.as_deref().unwrap_or(path);
        let content = file::read_to_string(path)?;
        let generated_header_url = existing_lockfile_doc_url(&content);
        let mut table: toml::Table = toml::from_str(&content)?;
        let lockfile_version = table
            .remove("lockfile_version")
            .map(|value| value.try_into())
            .transpose()?
            .unwrap_or(0);
        if lockfile_version > CURRENT_LOCKFILE_VERSION {
            bail!(
                "unsupported lockfile version {lockfile_version}; this mise supports up to version {CURRENT_LOCKFILE_VERSION}"
            );
        }

        let tools: toml::Table = table
            .remove("tools")
            .unwrap_or(toml::Table::new().into())
            .try_into()?;

        let mut lockfile = Lockfile {
            lockfile_version,
            generated_header_url,
            ..Default::default()
        };

        for (short, value) in tools {
            let versions = match value {
                toml::Value::Array(arr) => arr

View on GitHub (pinned to 533346cc37)