jdx/mise · error

missing archive reference

Error message

missing archive reference

What it means

The GitHub relay's authorize step only accepts archive requests in a recognized format (tarball/zipball suffix). After stripping the suffix it requires a non-empty reference (tag, branch or commit SHA) to build the api.github.com archive URL. If the reference is empty — e.g. the path was just ".zip" or a bare prefix — it refuses with "missing archive reference" rather than issuing a meaningless upstream request.

Source

Thrown at src/github_relay.rs:257

        "api.github.com"
    } else {
        "github.com"
    };
    let suffix = path.split_once('/').expect("validated path").1;
    let mut url = format!("https://{host}/{suffix}");
    let archive_repo = match p.as_slice() {
        ["api", "repos", _, _, "tarball" | "zipball", ..] => Some(name.clone()),
        ["web", _, _, "archive", rest @ ..] => {
            let reference = rest.join("/");
            let (kind, reference) = if let Some(reference) = reference.strip_suffix(".tar.gz") {
                ("tarball", reference)
            } else if let Some(reference) = reference.strip_suffix(".zip") {
                ("zipball", reference)
            } else {
                bail!("unsupported archive format");
            };
            if reference.is_empty() {
                bail!("missing archive reference");
            }
            // The API supplies short-lived private archive links; credentials
            // remain at the API origin and are never attached to that redirect.
            url = format!("https://api.github.com/repos/{name}/{kind}/{reference}");
            Some(name)
        }
        _ => None,
    };
    if let Some(query) = query {
        url.push('?');
        url.push_str(query);
    }
    Ok(Target {
        url,
        git,
        archive_repo,
    })
}

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Supply a concrete ref (tag, branch, or commit SHA) before the archive suffix, e.g. /archive/refs/tags/v1.2.3.tar.gz.
2. Fix the source of the empty value — check the version/ref variable being interpolated into the archive URL.
3. Fall back to a plain git clone or a direct codeload URL if you need an unnamed default-branch archive, which this authorize path does not accept.

Example fix

// before
let url = format!("https://github.com/foo/bar/archive/{version}.tar.gz"); // version == ""
// after
let version = version.non_empty().ok_or_else(|| eyre::eyre!("version required for archive download"))?;
let url = format!("https://github.com/foo/bar/archive/{version}.tar.gz");

fn archive_ref(url_path: &str) -> Option<&str> {
    for suffix in [".tar.gz", ".zip"] {
        if let Some(r) = url_path.strip_suffix(suffix) {
            if !r.is_empty() {
                return Some(r);
            }
        }
    }
    None
}
// call before issuing the request; bail early if None

fn has_archive_ref(reference: &str) -> bool {
    !reference.is_empty()
}

When it happens

Trigger: Calling the relay's authorize/operation path (directly or via forward / web_archives_use_scoped_api_downloads) with an archive reference that strips to empty: a path ending in ".tar.gz" or ".zip" with no repo ref before the suffix (e.g. /repo/archive/.zip).

Common situations: Templates or scripts interpolating a version variable that resolved to an empty string; misconfigured download URLs where the ref segment was accidentally dropped; programmatic URL builders emitting a trailing suffix only.

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

• additional asset '{}' is not an archive
• expected a GitHub repository in OWNER/REPO form
• unsupported GitHub operation
• unsupported query parameter
• unsupported archive format

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