unknown coverage mapping version reported by `llvm-wrapper`:

Error message

unknown coverage mapping version reported by `llvm-wrapper`: {raw_version}

What it means

This panic fires in `coverageinfo::mapgen::finalize` (mapgen.rs:50-53) when the LLVM-wrapper reports a coverage mapping version that `CovmapVersion::try_from` does not recognize. rustc currently only understands `Version7` (encoded as `6`, used by LLVM 18+); any other value from `llvm_cov::mapping_version()` triggers `panic!("unknown coverage mapping version reported by llvm-wrapper: {raw_version}")`. The guard ensures the Rust-side covmap writer and the LLVM-side reader agree on the binary format embedded in `__llvm_covmap`.

Source

Thrown at compiler/rustc_codegen_llvm/src/coverageinfo/mapgen.rs:52

    fn to_u32(self) -> u32 {
        self as u32
    }
}

/// Generates and exports the coverage map, which is embedded in special
/// linker sections in the final binary.
///
/// Those sections are then read and understood by LLVM's `llvm-cov` tool,
/// which is distributed in the `llvm-tools` rustup component.
pub(crate) fn finalize(cx: &mut CodegenCx<'_, '_>) {
    let tcx = cx.tcx;

    // Ensure that LLVM is using a version of the coverage mapping format that
    // agrees with our Rust-side code. Expected versions are:
    // - `Version7` (6) used by LLVM 18 onwards.
    let covmap_version =
        CovmapVersion::try_from(llvm_cov::mapping_version()).unwrap_or_else(|raw_version: u32| {
            panic!("unknown coverage mapping version reported by `llvm-wrapper`: {raw_version}")
        });
    assert_matches!(covmap_version, CovmapVersion::Version7);

    debug!("Generating coverage map for CodegenUnit: `{}`", cx.codegen_unit.name());

    // FIXME(#132395): Can this be none even when coverage is enabled?
    let Some(ref coverage_cx) = cx.coverage_cx else { return };

    let mut covfun_records = coverage_cx
        .instances_used()
        .into_iter()
        // Sort by symbol name, so that the global file table is built in an
        // order that doesn't depend on the stable-hash-based order in which
        // instances were visited during codegen.
        .sorted_by_cached_key(|&instance| tcx.symbol_name(instance).name)
        .filter_map(|instance| prepare_covfun_record(tcx, instance, true))
        .collect::<Vec<_>>();

View on GitHub (pinned to 22057b88b0)

Solutions

Update the rustc checkout to a commit whose `CovmapVersion` enum and `llvm-wrapper` both support the reported version.
Ensure the LLVM submodule matches the revision pinned by the rustc checkout (`./x.py build` after `git submodule update`).
Use a stable released toolchain for coverage work instead of a source build.
Disable `-Cinstrument-coverage` to bypass covmap generation until the version mismatch is resolved.

Example fix

// before
rustc +local-dev -Cinstrument-coverage main.rs   # LLVM bumped covmap version
// after
rustup update stable
rustc +stable -Cinstrument-coverage main.rs

Defensive patterns

Strategy: validation

Validate before calling

# Only LLVM coverage-mapping Version7 (==6) is accepted. The version comes from
# llvm-wrapper, so the rustc and llvm-tools-preview components MUST come from the
# same release. Validate component consistency before -Cinstrument-coverage.
rustc_version="$(rustc -vV | awk '/^release:/ {print $2}')"
if rustup component list --installed 2>/dev/null | grep -q llvm-tools-preview; then
  : # installed via rustup; consistency guaranteed by rustup
else
  echo 'llvm-tools-preview not installed; coverage may use a mismatched LLVM' >&2
fi
rustc -V >/dev/null 2>&1 || { echo 'rustc missing'; exit 1; }
# Reject toolchains where rustc and llvm-tools differ in date (nightly edge case).
rustup show | grep -E 'rustc|llvm-tools' || true

Try / catch

out="$(cargo build 2>&1)"; rc=$?
if [ $rc -ne 0 ]; then
  case "$out" in
    *"unknown coverage mapping version reported by"*)
      echo "rustc/llvm-tools coverage-format mismatch" >&2
      echo "fix: rustup toolchain install nightly --component llvm-tools-preview --force-non-host" >&2
      echo "     or upgrade to a stable release whose LLVM ships mapping Version7" >&2 ;;
    *) echo "$out" >&2 ;;
  esac
  exit $rc
fi

Prevention

Install llvm-tools-preview from the same toolchain as rustc: `rustup component add llvm-tools-preview`.
Do not copy llvm-cov / libLLVM from a different LLVM release into the toolchain sysroot.
Pin the toolchain date in rust-toolchain.toml so coverage runs against a known-compatible LLVM.
If a nightly regresses the mapping version, fall back to -Zinstrument-coverage=off until the components resync.
Verify with `llvm-cov --version` that the tool you invoke matches the rustc-shipped LLVM major version.

When it happens

Trigger: Compiling with coverage instrumentation (`-Cinstrument-coverage`) on a rustc whose bundled LLVM-wrapper returns a mapping version other than `6`. Triggered during the codegen-unit finalize step (`finalize()` at mapgen.rs:44) when `llvm_cov::mapping_version()` yields an unexpected `u32`.

Common situations: A source build of rustc where `rustc_llvm`/`llvm-wrapper` were updated to a newer LLVM (e.g. LLVM 19/20/21) that bumped the covmap version before rustc was patched to support it; mixing a rustc checkout with a non-matching LLVM submodule; running a dev build mid-rebase across an LLVM upgrade.

Related errors

AI-assisted analysis of rust-lang/rust@22057b88b0 (2026-08-03). Data as JSON: /data/errors/18a8f9f6b8613a26.json. Report an issue: GitHub.