Python lock is missing the requested root package

Error message

Python lock is missing the requested root package

What it means

After validating packages, validate_uv_lock requires that the graph actually contains the requested root package (a registry entry matching the normalized tool name and the requested version) AND that the virtual root was seen during traversal. If either flag is false, the lock does not cover the tool being installed and cannot be replayed for it.

Solutions

Re-lock the exact tool/version: `mise lock --bump <tool>`.
Confirm the requested version in mise.toml matches what was locked (e.g. resolve a prefix like `pipx:1.2` to a concrete version).
Inspect mise.lock to confirm the root package entry exists with matching name and version.
Delete the lock entry and run `mise lock` to regenerate it for the current request.

Example fix

// before: tool version changed but lock still pins 0.8
ruff = "pipx:0.9"   # mise.lock root says 0.8.0

// after
$ mise lock --bump ruff   # lock root now says 0.9.x

Defensive patterns

Strategy: validation

Validate before calling

const lock = parseLock('mise.lock');
if (!lock.packages.some(p => p.name === normalize(tool) && p.version === requestedVersion)) run('mise lock --bump <tool>');

Prevention

Lock the exact tool version you will install (resolve prefixes first)
Verify mise.lock root package after regenerating
Re-lock when switching tool names or versions in mise.toml

When it happens

Trigger: Thrown from validate_uv_lock when no package in the lock graph has the normalized tool name with version equal to tv.version, or the virtual root requirement block was never encountered; triggered via prepare_install_version, resolve_uv_lock, or install_uv_lock.

Common situations: Lock generated for a different tool or version than the one being installed; lock truncated or corrupted; tool renamed (normalization mismatch between the lock name and tool_name); requesting a version that was never locked.

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@533346cc37 (2026-09-17). Data as JSON: /api/errors/48538895ba7fd361. Report an issue: GitHub.

Appendix: source

Thrown at src/backend/pipx/lock.rs:421

                .get("wheels")
                .and_then(toml::Value::as_array)
                .filter(|v| !v.is_empty())
                .ok_or_else(|| {
                    eyre!("{name} has no published wheels; Python graph locks require wheels")
                })?;
            for wheel in wheels {
                let hash = wheel
                    .get("hash")
                    .and_then(toml::Value::as_str)
                    .and_then(|h| h.strip_prefix("sha256:"));
                if !hash.is_some_and(|h| h.len() == 64 && h.bytes().all(|c| c.is_ascii_hexdigit()))
                {
                    bail!("{name} has a wheel without a SHA256 hash");
                }
            }
        }
        if !root || !virtual_root {
            bail!("Python lock is missing the requested root package");
        }
        validate_portable_urls(&toml::Value::Table(lock.graph.clone()))?;
        // No arbitrary project settings or build systems are accepted from a lockfile.
        if lock.project.len() != 1 || project.len() != 4 {
            bail!("unsupported Python lock project settings");
        }
        Ok(())
    }

    pub(super) async fn install_uv_lock(
        &self,
        ctx: &InstallContext,
        tv: &ToolVersion,
    ) -> Result<()> {
        let lock = tv
            .uv_lock
            .as_ref()
            .ok_or_else(|| eyre!("missing uv lock"))?

View on GitHub (pinned to 533346cc37)