No lockfile URL found for {} on platform {} (--locked mode r

Error message

No lockfile URL found for {} on platform {} (--locked mode requires pre-resolved URLs)

What it means

In aqua install_version_, when running with ctx.locked (--locked mode), installs must use a URL already resolved and recorded in the lockfile. If no lockfile entry supplies a URL for this package/platform, the backend bails instead of performing network-based resolution, because locked mode forbids fresh resolution.

Source

Thrown at src/backend/aqua.rs:522

                if url.contains(&prefixed_version) || filename.contains(&prefixed_version) {
                    prefixed_version
                } else if url.contains(&format!("v{}", tv.version))
                    || filename.contains(&format!("v{}", tv.version))
                {
                    format!("v{}", tv.version)
                } else {
                    tv.version.clone()
                }
            } else if url.contains(&format!("v{}", tv.version))
                || filename.contains(&format!("v{}", tv.version))
            {
                format!("v{}", tv.version)
            } else {
                tv.version.clone()
            };
            (url, existing_url_api.clone(), v, filename, None)
        } else if ctx.locked {
            bail!(
                "No lockfile URL found for {} on platform {} (--locked mode requires pre-resolved URLs)",
                self.id,
                platform_key
            );
        } else {
            let (url, url_api, v, digest) = if pkg.package_type() == AquaPackageType::Http {
                let (url, resolved_version) =
                    resolve_aqua_http_url(&pkg, &v, v_prefixed.as_deref(), os(), arch()).await?;
                (url, None, resolved_version, None)
            } else if let Some(v_prefixed) = v_prefixed {
                // Try v-prefixed version first because most aqua packages use v-prefixed versions
                match self.get_url(&pkg, v_prefixed.as_ref()).await {
                    // If the url is already checked, use it
                    Ok((url, url_api, true, digest)) => (url, url_api, v_prefixed, digest),
                    Ok((url_prefixed, url_api_prefixed, false, digest_prefixed)) => {
                        let (url, url_api, _, digest) = self.get_url(&pkg, &v).await?;
                        // If the v-prefixed URL is the same as the non-prefixed URL, use it
                        if url == url_prefixed {

View on GitHub (pinned to afd2eddd3a)

Solutions

Regenerate the lockfile: run `mise install` once without --locked so URLs are resolved and written to mise.lock, commit it, then retry locked installs.
Check mise.lock contains an entry for this package + platform and update mise/mise.lock format if it was produced by an older version.
Drop --locked for this install if fresh resolution is acceptable.

Example fix

# before (CI)
mise install --locked   # No lockfile URL found for aqua:owner/repo on platform linux-x64
# after
mise install            # once, to re-resolve and update mise.lock
git add mise.lock && git commit -m "chore: update mise.lock"
mise install --locked   # now finds the pre-resolved URL

Defensive patterns

Strategy: fallback

Validate before calling

# shell: ensure lockfile has a URL for this package+platform before --locked
jq -e --arg pkg "aqua:owner/repo" '.packages[$pkg]' mise.lock >/dev/null || mise install

Try / catch

if mise install --locked fails with "No lockfile URL found"; then
  mise install            # re-resolve and rewrite mise.lock
  git add mise.lock
  mise install --locked
fi

Prevention

Commit an up-to-date mise.lock covering all target platforms used in CI.
Re-run unlocked install after changing tool versions or platforms.
Only use --locked in environments where mise.lock is guaranteed complete.

When it happens

Trigger: Installing an aqua tool with --locked where the mise.lock entry has no pre-resolved download URL for the target platform (lockfile written by an older version, or platform never installed before).

Common situations: CI running `mise install --locked` with a stale or incomplete mise.lock; lockfile committed before a new platform (e.g. linux-arm64) was ever resolved; package switched to an HTTP-type aqua package that the older lock predates.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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