gleam-lang/gleam · error

Attempt to download non-hex package from hex

Error message

Attempt to download non-hex package from hex

What it means

Panic in `HexDownloader::download`/ensure_package_downloaded (compiler-core/src/hex.rs:228) when asked to download a manifest package whose source is not Hex (Git or Local). Only Hex packages have an outer checksum and a tarball in the Hex cache; requesting a download for a Git or Local dependency is a caller bug, so the compiler panics instead of returning an error.

Solutions

1. Delete manifest.toml and re-run `gleam deps download` so the manifest is regenerated consistent with gleam.toml.
2. Ensure every dependency source in gleam.toml matches the manifest: run `gleam deps resolve` / any build command that re-syncs dependencies.
3. Check the manifest for Git/Local sourced packages that are being passed to Hex download; clear the stale build directory (`rm -rf build`).
4. If reproducible, file a bug — the caller should dispatch Git/Local packages to their own download paths rather than the Hex one.

Example fix

// before: stale manifest marks a git dep as Hex source
// manifest.toml: [packages] mydep -> source = "hex"
// after: regenerate manifest after changing gleam.toml
$ rm manifest.toml build -r && gleam deps download

// caller-side guard before hex download
if !matches!(package.source, ManifestPackageSource::Hex { .. }) {
    return Err(Error::UnsupportedPackageSource); // route git/local elsewhere
}

fn is_hex_package(p: &ManifestPackage) -> bool {
    matches!(p.source, ManifestPackageSource::Hex { .. })
}

When it happens

Trigger: `ensure_package_in_build_directory` resolving a dependency whose `ManifestPackage.source` is `Git` or `Local` but routing it through the Hex download path — e.g. a manifest whose package origin changed (dependency switched from Hex to git/local in gleam.toml) without the manifest being updated, or stale cached manifest entries.

Common situations: Mixing hex and git/local dependencies and having an out-of-date manifest; editing gleam.toml to point a package at git while an old manifest still lists it as Hex (or vice versa); corrupted or hand-edited manifest.toml.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• verified_releases covers every resolved hex package
• == should be a valid range
• aliased non constant value
• archive entries
• archive entry

AI-assisted analysis of gleam-lang/gleam@15b07c7830 (2026-09-14). Data as JSON: /api/errors/71d25357b958e061. Report an issue: GitHub.

Appendix: source

Thrown at compiler-core/src/hex.rs:228

        Self {
            fs_reader: DebugIgnore(fs_reader),
            fs_writer: DebugIgnore(fs_writer),
            http: DebugIgnore(http),
            untar: DebugIgnore(untar),
            hex_config: hexpm::Config::new(),
            credentials: DebugIgnore(credentials),
            paths,
        }
    }

    pub async fn ensure_package_downloaded(
        &self,
        package: &ManifestPackage,
    ) -> Result<bool, Error> {
        let outer_checksum = match &package.source {
            ManifestPackageSource::Hex { outer_checksum } => outer_checksum,
            ManifestPackageSource::Git { .. } | ManifestPackageSource::Local { .. } => {
                panic!("Attempt to download non-hex package from hex")
            }
        };

        let tarball_path = paths::global_package_cache_package_tarball(outer_checksum);
        if self.fs_reader.is_file(&tarball_path) {
            tracing::info!(
                package = package.name.as_str(),
                version = %package.version,
                "package_in_cache"
            );
            return Ok(false);
        }
        tracing::info!(
            package = &package.name.as_str(),
            version = %package.version,
            "downloading_package_to_cache"
        );

View on GitHub (pinned to 15b07c7830)