What causes "Failed to resolve tool version list for {ba}: {err}" in jdx/mise?

Fix the underlying cause shown in `{err}` (network, token, or bad version string in config).

Failed to resolve tool version list for {ba}: {err}

Error message

Failed to resolve tool version list for {ba}: {err}

What it means

While resolving a toolset, mise warns (once, via `warn_once!`) "Failed to resolve tool version list for {backend}: {err}" when a tool's version list cannot be resolved but the error is not a required-channel resolution error. The command continues with the remaining tools instead of aborting. Only errors flagged by `Error::is_required_channel_resolution_err` abort immediately.

Source

Thrown at src/toolset/mod.rs:179

                (config.clone(), ba, tvl, opts.clone(), reporter)
            })
            .collect::<Vec<_>>();
        let tvls = parallel::parallel(
            versions,
            |(config, ba, mut tvl, opts, reporter)| async move {
                let result = crate::ui::resolve_progress::scope(
                    reporter.as_ref().map(|p| p.reporter()),
                    tvl.resolve(&config, &opts),
                )
                .await;
                if let Some(reporter) = reporter {
                    reporter.complete(result.as_ref().err().map(|e| e.to_string()).as_deref());
                }
                if let Err(err) = result {
                    if Error::is_required_channel_resolution_err(&err) {
                        return Err(err);
                    }
                    // warn_once: a command may resolve the same toolset more than
                    // once, and repeating an identical failure adds no information.
                    warn_once!("Failed to resolve tool version list for {ba}: {err}");
                }
                Ok((ba, tvl))
            },
        )
        .await?;
        self.versions = tvls.into_iter().collect();
        if let Some(progress) = progress.as_mut() {
            progress.finish(vec![]);
        }
        Ok(())
    }

    pub(crate) fn list_missing_plugins(&self) -> Vec<String> {
        self.versions
            .iter()
            .filter(|(_, tvl)| {

View on GitHub (pinned to afd2eddd3a)

Solutions

Fix the underlying cause shown in `{err}` (network, token, or bad version string in config).
Set a GITHUB_TOKEN if the failure is API rate limiting (`export GITHUB_TOKEN=$(gh auth token)`).
Pin a concrete version in mise.toml instead of `latest`/a loose prefix to avoid list resolution.
Run `mise ls-remote <tool>` to verify the backend can list versions at all.

Example fix

// before
[tools]
node = "lts"   # resolution fails offline
// after
[tools]
node = "20.11.0"  # pinned, no version-list lookup needed

Defensive patterns

Strategy: fallback

Validate before calling

mise ls-remote <tool>  # verify the backend can list versions before relying on latest/prefix resolution

Prevention

Pin concrete versions in mise.toml instead of `latest` or loose prefixes.
Export GITHUB_TOKEN to avoid API rate limits during resolution.
Check network/proxy settings if multiple tools warn at once.
Run with MISE_DEBUG=1 to see the underlying per-tool error.

When it happens

Trigger: Any command that resolves the toolset (`mise install`, `mise exec`, activation, run) where a tool's `latest`/prefix/channel lookup fails — e.g. backend cannot reach its registry, `latest` cannot be determined, or the requested prefix matches nothing.

Common situations: Network/API failures reaching GitHub/aqua/npm registries; typos in version prefixes in mise.toml/.tool-versions; a plugin returning an empty or broken version list; missing/expired GITHUB_TOKEN causing 429s.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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