cross-rs/cross · error

unknown prerelease tag

Error message

unknown prerelease tag {x}

What it means

rustc_channel parses the prerelease segment of a rustc version string into a Channel enum (Stable, Dev, Beta, Nightly). When the prerelease tag after the `.` is not one of the four recognized values, it aborts with this error. The library throws it because it can only classify toolchains it explicitly knows about.

Solutions

1. Run `rustc -vV` and inspect the prerelease part after the first `.`; use a toolchain with a standard stable/beta/nightly/dev version string
2. If a custom toolchain is intentional, adjust the toolchain selection so rustc_channel is only used with official rustup toolchains
3. Update the toolchain (rustup update) so its version matches a known channel format
4. Patch the match in src/rustc_channel to recognize your custom prerelease tag if you maintain the fork

Example fix

// before
"nightly-2024-01-01" // arbitrary prerelease tag -> bail! "unknown prerelease tag"
// after
rustup update nightly // or pin a toolchain whose version reports exactly 'nightly'

fn is_known_channel(v: &str) -> bool {
    let pre = v.split('.').nth(1).unwrap_or("");
    matches!(pre, "" | "dev" | "beta" | "nightly")
}

fn is_known_channel(pre: &str) -> bool {
    matches!(pre, "" | "dev" | "beta" | "nightly")
}

match rustc_channel(&version) {
    Ok(ch) => use(ch),
    Err(e) if e.to_string().contains("unknown prerelease tag") => fallback_to_stable_or_skip(e),
    Err(e) => return Err(e),
}

When it happens

Trigger: The prerelease portion of the version string produced by rustc -vV does not exactly equal '', 'dev', 'beta', or 'nightly'. This happens when rustc_channel receives a version string with a custom or unexpected prerelease suffix.

Common situations: Using a custom or vendor-built toolchain whose version string has a nonstandard prerelease tag (e.g. 'nightly-2024-01-01', 'master', or a fork's own tag); parsing output from a tool other than rustc; toolchain upgrade changing version format.

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

• commit hash must be at least
• invalid toolchain
• no rust-std component available for
• should contain one item
• could not determine what toolchain to use for image…

AI-assisted analysis of cross-rs/cross@8c1a8aa4b6 (2026-09-13). Data as JSON: /api/errors/adddbeba937d6691. Report an issue: GitHub.

Appendix: source

Thrown at src/rustup.rs:318

        {
            install_component("clippy", toolchain, msg_info)?;
        }
    }
    Ok(())
}

fn rustc_channel(version: &Version) -> Result<Channel> {
    match version
        .pre
        .split('.')
        .next()
        .expect("rust prerelease version should contain `.`")
    {
        "" => Ok(Channel::Stable),
        "dev" => Ok(Channel::Dev),
        "beta" => Ok(Channel::Beta),
        "nightly" => Ok(Channel::Nightly),
        x => eyre::bail!("unknown prerelease tag {x}"),
    }
}

impl QualifiedToolchain {
    fn multirust_channel_manifest_path(&self) -> PathBuf {
        self.get_sysroot()
            .join("lib/rustlib/multirust-channel-manifest.toml")
    }

    pub fn rustc_version_string(&self) -> Result<Option<String>> {
        let path = self.multirust_channel_manifest_path();
        if path.exists() {
            let contents =
                std::fs::read(&path).wrap_err_with(|| format!("couldn't open file `{path:?}`"))?;
            let manifest: toml::value::Table = toml::from_str(std::str::from_utf8(&contents)?)?;
            return Ok(manifest
                .get("pkg")
                .and_then(|pkg| pkg.get("rust"))

View on GitHub (pinned to 8c1a8aa4b6)