jdx/mise · error

unsupported aqua package format: {format}

Error message

unsupported aqua package format: {format}

What it means

effective_extraction_format maps the aqua package's declared format string to an ExtractionFormat. If the format extension is not a recognized archive type (tar/tar.gz/zip/etc.) and is not one of the accepted special values (empty, dmg, pkg), mise rejects the package rather than guessing how to extract it.

Source

Thrown at src/backend/aqua.rs:2998

        Ok(())
    }

    fn record_cosign_provenance(&self, tv: &mut ToolVersion) {
        self.record_provenance(tv, ProvenanceType::Cosign);
    }

    fn record_provenance(&self, tv: &mut ToolVersion, provenance: ProvenanceType) {
        let platform_key = self.get_platform_key();
        let pi = tv.lock_platforms.entry(platform_key).or_default();
        if pi.provenance.as_ref().is_none_or(|p| *p < provenance) {
            pi.provenance = Some(provenance);
        }
    }

    fn effective_extraction_format(pkg: &AquaPackage, format: &str) -> Result<ExtractionFormat> {
        let extraction_format = ExtractionFormat::from_ext(format);
        if extraction_format.is_none() && !matches!(format, "" | "dmg" | "pkg") {
            bail!("unsupported aqua package format: {format}");
        }
        let extraction_format = extraction_format.unwrap_or(ExtractionFormat::Raw);
        if pkg.package_type() == AquaPackageType::GithubArchive
            && extraction_format == ExtractionFormat::Raw
        {
            // The aqua registry can omit format for GitHub-generated archive downloads.
            // Historically Raw reached untar/open_tar, which treated it as gzip-tar.
            Ok(ExtractionFormat::TarGz)
        } else {
            Ok(extraction_format)
        }
    }

    fn install(
        &self,
        ctx: &InstallContext,
        tv: &ToolVersion,
        pkg: &AquaPackage,

View on GitHub (pinned to afd2eddd3a)

Solutions

  1. Update mise so the embedded aqua registry / ExtractionFormat parsing supports the new format
  2. Install the tool via a different backend that handles the format (e.g. github backend or a package-manager backend)
  3. Pin a version of the tool whose assets use a supported format (tar.gz, zip, raw binary, dmg, pkg)
  4. If you author the aqua package entry, fix the `format` field to a recognized extension or remove it for raw binaries

Example fix

# before (aqua package YAML)
format: deb

# after
format: tar.gz
Defensive patterns

Strategy: validation

Validate before calling

// pre-check the package's declared format before installing via aqua
const pkg = await fetchAquaRegistryEntry(pkgName);
const ok = ["", "tar.gz", "tgz", "tar.xz", "tar.bz2", "zip", "raw", "dmg", "pkg"];
if (!ok.includes(pkg.format ?? "")) {
  console.warn(`format '${pkg.format}' not supported by mise aqua backend; pick another backend`);
}

Try / catch

try {
  await $`mise install aqua:owner/repo`;
} catch (e) {
  if (String(e).includes("unsupported aqua package format")) {
    await $`mise use github:owner/repo`; // fall back to release-asset backend
  } else throw e;
}

Prevention

When it happens

Trigger: Installing an aqua package whose registry entry declares a `format:` value that is neither a known archive extension nor '' | 'dmg' | 'pkg', when install reaches format resolution (src/backend/aqua.rs:2998).

Common situations: Aqua registry entry uses an unusual or newly introduced format string; typos like 'targz' or 'binary'; package ships an installer format mise's aqua backend doesn't handle (e.g. msi, deb, rpm).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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