jdx/mise · error

github_content package requires `path`

Error message

github_content package requires `path`

What it means

Aqua packages of type github_content fetch a single file from a GitHub repository at a path. If such a package lacks the required `path` field in its config, the backend cannot construct the download URL and throws this error during lock-info resolution.

Solutions

1. Add the `path` field to the github_content package config, pointing at the file inside the repo (e.g. path: install.sh)
2. If you meant to fetch a whole release/archive, change the package type to github_release or github_archive instead of github_content
3. If this comes from an upstream registry package, pin to a registry version where the package defines `path` or report the registry entry

Example fix

# before
packages:
  - type: github_content
    repo_owner: someowner
    repo_name: sometool
# after
packages:
  - type: github_content
    repo_owner: someowner
    repo_name: sometool
    path: sometool

if pkg.package_type() == AquaPackageType::GithubContent && pkg.path.is_none() {
    return Err(anyhow!("github_content package requires `path`"));
}

fn github_content_has_path(pkg: &AquaPackage) -> bool {
    pkg.package_type() != AquaPackageType::GithubContent || pkg.path.is_some()
}

match resolve_lock_info(pkg, v).await {
    Err(e) if e.to_string().contains("github_content package requires `path`") => {
        eprintln!("fix the registry entry: add `path` to the github_content package");
    }
    r => r?,
}

When it happens

Trigger: Defining (or overriding) an aqua package with type github_content but omitting `path` (and only repo/repo_owner/repo_name given), while resolve_lock_info builds the URL/API URLs for a version.

Common situations: Copy-pasting a github_archive or github_release package config and switching only the type; hand-writing a custom registry entry for a single-file tool and forgetting `path`; upstream aqua-registry package missing the field after a schema change.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• aqua package does not have repo_owner and/or repo_name.
• aqua var ` ` must be a string, got
• at least one bin path should exist
• conflicting aqua var
• a provided source resolves to a path

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/146030ee5c405412. Report an issue: GitHub.

Appendix: source

Thrown at src/backend/aqua.rs:868

                        }
                    }
                }
                result
            }
            AquaPackageType::GithubArchive => (
                Some(self.github_archive_url(&pkg, &v)),
                Some(self.github_archive_api_url(&pkg, &v)),
                None,
            ),
            AquaPackageType::GithubContent => {
                if pkg.path.is_some() {
                    (
                        Some(self.github_content_url(&pkg, &v)),
                        Some(self.github_content_api_url(&pkg, &v)),
                        None,
                    )
                } else {
                    bail!("github_content package requires `path`")
                }
            }
            AquaPackageType::Http => {
                let (url, resolved_version) =
                    resolve_aqua_http_url(&pkg, &v, v_prefixed.as_deref(), target_os, target_arch)
                        .await?;
                v = resolved_version;
                (Some(url), None, None)
            }
            _ => (None, None, None),
        };

        let name = url.as_ref().map(|u| get_filename_from_url(u));
        if let Some(filename) = &name {
            pkg = Self::apply_selected_asset_libc_replacement(pkg, target_os, filename);
        }

        // Try to get checksum from checksum file if not available from GitHub API

View on GitHub (pinned to 533346cc37)