jdx/mise · error

missing archive reference

Error message

missing archive reference

What it means

When a `web/OWNER/REPO/archive/...` URL ends in `.tar.gz` or `.zip`, the remaining text before that suffix is the git reference to archive (e.g. `refs/tags/v1.0` or `main`). If that reference is empty — meaning the path ends right at the suffix with nothing identifying what to archive — the relay rejects the request since there is no meaningful upstream URL to build.

Solutions

1. Include the git reference before the extension, e.g. `/web/org/repo/archive/refs/tags/v1.0.tar.gz` or `/web/org/repo/archive/main.zip`
2. Fix the templating/variable so the version or ref is actually substituted into the URL
3. Verify the path was not truncated — the full `refs/tags/<tag>` (or branch name) must be present

Example fix

// before
GET /web/org/repo/archive/refs/tags/.tar.gz
// after
GET /web/org/repo/archive/refs/tags/v1.0.tar.gz

fn archive_ref_is_present(path: &str) -> bool {
    for ext in [".tar.gz", ".zip"] {
        if let Some(rest) = path.strip_suffix(ext) {
            return rest.rsplit('/').next().map_or(false, |s| !s.is_empty());
        }
    }
    false
}
assert!(archive_ref_is_present("/web/o/r/archive/refs/tags/v1.0.tar.gz"));

match authorize(&scope, method, path, query) {
    Err(e) if e.to_string().contains("missing archive reference") => {
        eprintln!("archive URL is missing the git ref before the extension");
    }
    Ok(t) => forward(t),
    Err(e) => return Err(e),
}

When it happens

Trigger: Requests like `/web/org/repo/archive/.tar.gz` or `/web/org/repo/archive/.zip` where the reference portion before the extension is empty (a tag/ref name consisting solely of the stripped extension, or a path where the ref got dropped).

Common situations: URL templates where a `${version}`/`${ref}` variable expanded to empty because the version was not provided; a build script stripping the ref accidentally (e.g. an over-eager suffix trim leaving nothing); copy-paste of an archive URL that lost its ref segment.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• unsupported archive format
• expected a GitHub repository in OWNER/REPO form
• GitHub relay is not connected
• GitHub relay permits read-only repository operations only
• invalid relay path

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

Appendix: 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 533346cc37)