What causes "could not determine OS release" in jdx/mise?

Export the GitHub Actions-style hint: `ImageOS=ubuntu24 mise install erlang@27.1` (maps to the ubuntu-24.04 build)

could not determine OS release

Error message

could not determine OS release

What it means

To choose the hex.pm Ubuntu build, mise must identify the distro: first the GitHub Actions ImageOS env var, then /etc/os-release (ID + VERSION_ID via linux_os_release). If neither yields a string, it cannot form the builds.txt URL and bails. Only fatal with erlang.compile=false; otherwise the install quietly falls back to compiling from source.

Source

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

            Self::linux_precompiled_os_version().ok()
        } else {
            None
        }
    }

    fn linux_precompiled_os_version() -> Result<String> {
        let os_ver = if Platform::current().is_linux() {
            if let Ok(os) = std::env::var("ImageOS") {
                match os.as_str() {
                    "ubuntu24" => "ubuntu-24.04".to_string(),
                    "ubuntu22" => "ubuntu-22.04".to_string(),
                    "ubuntu20" => "ubuntu-20.04".to_string(),
                    _ => os,
                }
            } else if let Some(os_release) = linux_os_release() {
                format!("{}-{}", os_release.id, os_release.version_id)
            } else {
                bail!("could not determine OS release");
            }
        } else {
            // Cross-platform Linux lock resolution cannot inspect the target
            // distro, so use Bob's newest supported Ubuntu build.
            "ubuntu-24.04".to_string()
        };

        // Currently, Bob only builds for Ubuntu, so we have to check that we're on Ubuntu,
        // and on a supported version.
        if !["ubuntu-20.04", "ubuntu-22.04", "ubuntu-24.04"].contains(&os_ver.as_str()) {
            bail!("unsupported OS version: {os_ver}");
        }
        Ok(os_ver)
    }

    fn macos_asset_name(target: &PlatformTarget) -> Result<String> {
        let arch = match target.arch_name() {
            "x64" => "x86_64",

View on GitHub (pinned to 6f52dcdf99)

Solutions

Export the GitHub Actions-style hint: `ImageOS=ubuntu24 mise install erlang@27.1` (maps to the ubuntu-24.04 build)
Base the image on Ubuntu/Debian so /etc/os-release exists with ID and VERSION_ID
Or sidestep distro detection: `mise settings set erlang.compile true`

Example fix

# before
$ docker run --rm my-distroless-image mise install erlang@27.1
ERROR: could not determine OS release

# after
$ docker run --rm -e ImageOS=ubuntu24 my-distroless-image mise install erlang@27.1

Defensive patterns

Strategy: validation

Validate before calling

# make distro detection possible in minimal containers
if [ ! -r /etc/os-release ] && [ -z "${ImageOS:-}" ]; then
  export ImageOS=ubuntu24   # only valid if the runtime really is ubuntu-24.04 glibc
fi
mise install erlang@27.1

Type guard

has_os_identity() { [ -n "${ImageOS:-}" ] || grep -q '^ID=' /etc/os-release 2>/dev/null; }

Prevention

Don't strip /etc/os-release when shrinking Docker images — many tools need it
In GitHub Actions runners the ImageOS var is set automatically; reproduce it in custom containers

When it happens

Trigger: `mise install erlang` (with compile=false) inside a stripped container that has no parsable /etc/os-release and no ImageOS env: distroless images, scratch-based images, some embedded/minimal BusyBox rootfs, or an os-release file missing ID/VERSION_ID fields.

Common situations: Hardened Docker images built by removing docs/metadata; CI runners built from scratch rootfs; chroot/proot environments where /etc/os-release was not mounted.

Related errors

AI-assisted analysis of jdx/mise@6f52dcdf99 (2026-08-22). Data as JSON: /api/errors/459ab5588f47c2b9. Report an issue: GitHub.