What causes "{}@{} is not in the lockfile hint: {hint}" in jdx/mise?

Run `mise lock` to record the requested versions in mise.lock, then retry the locked install.

@ is not in the lockfile hint

Error message

{}@{} is not in the lockfile
hint: {hint}

What it means

resolve_version in tool_version.rs fails when `tool_config.locked` (or `--locked`) is in effect but the exact tool@version requested is absent from mise.lock. The hint distinguishes a config-level lock (run `mise lock`) from an invocation-level `--locked` (run plain `mise install`).

Solutions

Run `mise lock` to record the requested versions in mise.lock, then retry the locked install.
If the lock came from `--locked` on the command, run `mise install` once without --locked to update the lockfile.
Temporarily disable `tool_config.locked` if you intend to float versions instead of pinning.

Example fix

// before
$ mise install --locked
error: node@22.3.0 is not in the lockfile
// after
$ mise lock && mise install --locked

Defensive patterns

Strategy: validation

Validate before calling

// Before running a locked install, ensure the lockfile is current:
// mise lock && git diff --exit-code mise.lock
// In CI, fail early if config changed without re-locking:
git diff --quiet HEAD -- mise.toml mise.lock || (echo 'mise.lock out of date; run mise lock' && exit 1)

Try / catch

try {
  run('mise install --locked');
} catch (e) {
  if (/is not in the lockfile/.test(String(e))) {
    run('mise lock');
    run('mise install --locked');
  } else throw e;
}

Prevention

Run `mise lock` and commit mise.lock whenever you change tool versions in mise.toml.
In CI, use --locked intentionally and keep the lockfile fresh on main.
Add a pre-commit check that mise.lock is up to date with mise.toml.

When it happens

Trigger: Running `mise install --locked` (or having `tool_config.locked = true`) after the config requested a new/different tool version that hasn't been recorded in mise.lock yet; also after editing mise.toml versions without re-locking.

Common situations: A teammate bumped a tool version in mise.toml and committed without running `mise lock`; CI runs with --locked and fails; a fresh clone has a stale mise.lock relative to config changes.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/toolset/tool_version.rs:404

                request.lockfile_resolve_with_prefix(config, lock_query, lock_prefix_boundary)?
        {
            return Ok(Self::from_lockfile(request.clone(), lt));
        }
        let settings = Settings::get();
        let tool_config_locked = config.tool_config_locked(request.source());
        let invocation_locked = config.invocation_locked_for(request.source(), settings.locked);
        if (invocation_locked || tool_config_locked)
            && opts.use_locked_version
            && settings.lockfile_enabled()
            && !has_linked_version(request.ba())
            && request.source().path().is_some()
        {
            let hint = if tool_config_locked && !invocation_locked {
                "Run `mise lock` to update the lockfile, or disable `tool_config.locked`"
            } else {
                "Run `mise install` without --locked to update the lockfile"
            };
            bail!(
                "{}@{} is not in the lockfile\nhint: {hint}",
                request.ba().short,
                request.version()
            );
        }

        match v.split_once(':') {
            Some((ref_type @ ("ref" | "tag" | "branch" | "rev"), r)) => {
                return Ok(Self::resolve_ref(
                    r.to_string(),
                    ref_type.to_string(),
                    &request,
                ));
            }
            Some(("path", p)) => {
                return Self::resolve_path(PathBuf::from(p), &request);
            }
            Some(("prefix", p)) => {

View on GitHub (pinned to afd2eddd3a)