jdx/mise · error

at least one bin path should exist

Error message

at least one bin path should exist

What it means

During aqua package installation the code maps every configured executable name to a bin path and then takes the first element with `.expect`. The panic means the `bin_paths` vector is empty — the aqua package manifest's `files`/`bin` section resolved to zero installable executables, so there is nothing to link into the install directory.

Source

Thrown at src/backend/aqua.rs:3053

        if bin_names.is_empty() {
            let fallback_name = pkg
                .name
                .as_deref()
                .and_then(|n| n.split('/').next_back())
                .unwrap_or(&pkg.repo_name);
            bin_names = vec![Cow::Borrowed(fallback_name)];
        }
        let bin_paths: Vec<_> = bin_names
            .iter()
            .map(|name| {
                let name_str: &str = name.as_ref();
                install_path.join(name_str)
            })
            .map(|path| complete_windows_ext(path, pkg, os(), v))
            .collect();
        let first_bin_path = bin_paths
            .first()
            .expect("at least one bin path should exist");
        let extract_opts = ExtractOptions {
            pr: Some(ctx.pr.as_ref()),
            ..Default::default()
        };
        let extraction_format = Self::effective_extraction_format(pkg, format)?;
        let mut make_executable = false;
        if let AquaPackageType::GithubArchive = pkg.package_type() {
            file::extract_archive(
                &tarball_path,
                &install_path,
                extraction_format,
                &extract_opts,
            )?;
            make_executable = true;
        } else if let AquaPackageType::GithubContent = pkg.package_type() {
            if let Some(parent) = first_bin_path.parent() {
                file::create_dir_all(parent)?;
            }

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Inspect the tool's aqua registry entry and confirm its `files:` section declares at least one valid `name`/`src` pair
2. Check the installed version's archive layout — if upstream renamed/moved the binary, fix or update the registry entry
3. Pin a different version whose layout matches the config (`mise use aqua:<pkg>@<older-version>`)
4. Report/fix the aqua-registry package definition

Example fix

# before (registry entry, files section omitted/empty)
packages:
  - type: github_release
    repo_owner: example
    repo_name: tool
# after
packages:
  - type: github_release
    repo_owner: example
    repo_name: tool
    asset: tool_{{.OS}}_{{.Arch}}.tar.gz
    files:
      - name: tool
        src: tool

# validate before installing
mise ls-remote aqua:<owner>/<repo>   # entry exists
mise x aqua:<owner>/<repo>@<v> -- which <bin>  # bin resolves for this platform/version

if (pkg.files ?? []).length === 0) throw new Error(`aqua package ${pkg.name} declares no files/bins`);

if mise install aqua:owner/repo 2>&1 | grep -q 'at least one bin path'; then echo 'registry entry has no resolvable bins — fix files: section or pin another version'; fi

When it happens

Trigger: Installing an aqua package whose parsed package config yields no executable entries: an empty or missing `files:` section, a `bin` name that matches no file in the archive, or platform/version filtering that drops all entries.

Common situations: A typo'd or missing `files[].name`/`src` in the aqua registry entry, an archive that changed layout in a new release so the declared bin no longer exists, or a Windows/OS-specific override filtering out all bins.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• conflicting aqua var `{key}`: use only one spelling
• github_content package requires `path`
• aqua package {} does not have repo_owner and/or repo_name.
• aqua var `{}` must be a string, got {}
• GitHub API URL should be valid

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