expected exactly one Hex OTP build record for

Error message

expected exactly one Hex OTP build record for {release_tag}, found {}

What it means

parse_hex_build_checksum scans the Hex OTP builds checksum file for the line whose first field equals the release tag. If zero or multiple lines match, the lock cannot be established unambiguously, so it bails with this error.

Solutions

Retry later or after `mise lock` to re-fetch an updated Hex builds file
Choose a different Erlang version whose Hex build record exists
Check the Hex builds checksum file for the release tag and report upstream duplicates if found

Defensive patterns

Strategy: retry

Validate before calling

# pre-check Hex builds data for the tag before installing
curl -s https://builds.hex.pm/builds/otp/amd64/ubuntu-24.04/builds.txt | grep -c "^OTP-26.2.5"

Try / catch

mise install erlang@26.2.5 || { sleep 30; mise lock && mise install erlang@26.2.5; }

Prevention

Install Erlang versions a bit after release so Hex builds propagate
Check builds.hex.pm for the exact release tag first
Avoid pinning brand-new OTP versions in locked CI pipelines

When it happens

Trigger: Fetching a precompiled Linux Erlang build whose release tag is missing from the Hex builds file (deleted/renamed build) or appears more than once (duplicated upload).

Common situations: Very new or yanked OTP releases where the Hex build record has not propagated, or upstream Hex data anomalies causing duplicate records.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/plugins/core/erlang.rs:817

        lock_platforms
            .get(platform_key)
            .is_some_and(|pi| pi.install.as_deref() == Some("source"))
    } else {
        erlang_compile == Some(true)
    }
}

fn parse_hex_build_checksum(builds: &str, release_tag: &str) -> Result<String> {
    let matching = builds
        .lines()
        .filter_map(|line| {
            let parts = line.split_whitespace().collect::<Vec<_>>();
            (parts.first() == Some(&release_tag)).then_some(parts)
        })
        .collect::<Vec<_>>();

    if matching.len() != 1 {
        bail!(
            "expected exactly one Hex OTP build record for {release_tag}, found {}",
            matching.len()
        );
    }

    let checksum = matching[0]
        .get(3)
        .ok_or_else(|| eyre::eyre!("Hex OTP build record for {release_tag} has no checksum"))?;
    if !regex!(r"^[0-9a-f]{64}$").is_match(checksum) {
        bail!("invalid Hex OTP checksum for {release_tag}: {checksum}");
    }

    Ok(format!("sha256:{checksum}"))
}

#[cfg(any(linux, test))]
fn require_locked_precompiled_checksum(version: &str, checksum: Option<&str>) -> Result<String> {
    let checksum = checksum.ok_or_else(|| {

View on GitHub (pinned to 533346cc37)