jdx/mise · error

unsupported archive format

Error message

unsupported archive format

What it means

When authorizing a web archive download (`/web/{owner}/{repo}/archive/{ref}.<ext>`), `authorize` recognizes only `.tar.gz` (tarball) and `.zip` (zipball) suffixes. Any other extension — or none — fails with this error, and the stripped suffix must leave a non-empty reference.

Source

Thrown at src/github_relay.rs:254

        }
    }
    let host = if p[0] == "api" {
        "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,

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Use `.tar.gz` for the tarball or `.zip` for the zipball suffix: `/web/{owner}/{repo}/archive/{ref}.tar.gz`.
2. Ensure the ref remains non-empty after the suffix is stripped (don't pass just `archive/.zip`).
3. If you need another format, convert locally after downloading the supported `.tar.gz`/`.zip` artifact.

Example fix

// before
let path = "/web/octocat/hello-world/archive/main.tar.bz2";
// after
let path = "/web/octocat/hello-world/archive/main.tar.gz";

fn archive_suffix_ok(reference: &str) -> bool {
    let stripped = reference
        .strip_suffix(".tar.gz")
        .or_else(|| reference.strip_suffix(".zip"));
    stripped.map(|s| !s.is_empty()).unwrap_or(false)
}
assert!(archive_suffix_ok("v1.2.0.tar.gz"));

match relay::operation("GET", path, None) {
    Err(e) if e.to_string().contains("archive format") => eprintln!("use .tar.gz or .zip suffix: {path}"),
    Err(e) => return Err(e),
    Ok(t) => t,
}

When it happens

Trigger: Requesting an archive URL whose reference ends in something other than `.tar.gz` or `.zip`, e.g. `/web/o/r/archive/main.tar.bz2`, `/web/o/r/archive/v1.tar`, `/web/o/r/archive/v1`, or `/web/o/r/archive/.zip` (empty ref after stripping).

Common situations: Copy codeload URLs in other formats (`tar.bz2`, `zip.gz`); tooling that defaults to a different compression; building the URL manually and forgetting the extension entirely; a bare ref where the suffix got truncated by string handling.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• additional asset '{}' is not an archive
• Invalid checksum: {checksum}
• expected a GitHub repository in OWNER/REPO form
• unsupported GitHub operation
• repository is outside the approved relay scope

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