rust-lang/rust · error · anyhow::Error

unknown mapping kind: {raw_mapping_kind:#x}

Error message

unknown mapping kind: {raw_mapping_kind:#x}

What it means

Thrown by read_raw_mapping_kind in coverage-dump when the decoded raw mapping-kind ULEB128 value (after the low two bits are checked and found non-code) has a high-nibble value not in {0,2,4,5,6}. Known kinds: 0=zero/code-handled, 2=Skip, 4=Branch, 5=MCDCDecision, 6=MCDCBranch. Any other value means the payload contains an unrecognized mapping kind, typically from a newer LLVM or a corrupt payload.

Source

Thrown at src/tools/coverage-dump/src/covfun.rs:237

                    let conditions_num = self.read_uleb128_u32()?;
                    Ok(MappingKind::MCDCDecision { bitmap_idx, conditions_num })
                }
                6 => {
                    let r#true = self.read_simple_term()?;
                    let r#false = self.read_simple_term()?;
                    let condition_id = self.read_uleb128_u32()?;
                    let true_next_id = self.read_uleb128_u32()?;
                    let false_next_id = self.read_uleb128_u32()?;
                    Ok(MappingKind::MCDCBranch {
                        r#true,
                        r#false,
                        condition_id,
                        true_next_id,
                        false_next_id,
                    })
                }

                _ => Err(anyhow!("unknown mapping kind: {raw_mapping_kind:#x}")),
            }
        }
    }

    fn read_raw_mapping_region(&mut self) -> anyhow::Result<MappingRegion> {
        let start_line_offset = self.read_uleb128_u32()?;
        let start_column = self.read_uleb128_u32()?;
        let end_line_offset = self.read_uleb128_u32()?;
        let end_column = self.read_uleb128_u32()?;
        Ok(MappingRegion { start_line_offset, start_column, end_line_offset, end_column })
    }
}

/// Enum that can hold a constant zero value, the ID of an physical coverage
/// counter, or the ID (and operation) of a coverage-counter expression.
///
/// Terms are used as the operands of coverage-counter expressions, as the arms
/// of branch mappings, and as the value of code/gap mappings.

View on GitHub (pinned to 7088e4b63a)

Solutions

  1. Verify the coverage artifact comes from an LLVM whose mapping kinds are all in the set coverage-dump knows.
  2. If LLVM added a new kind, add a match arm in read_raw_mapping_kind with its discriminant and decoding logic.
  3. Re-generate the coverage data to rule out corruption.
  4. Inspect the raw bytes printed just above the error to confirm the ULEB128 decode is consuming the expected offset.

Example fix

// before
match high {
    0 => unreachable!(...),
    2 => Ok(MappingKind::Skip),
    4 => Ok(MappingKind::Branch { ... }),
    5 => Ok(MappingKind::MCDCDecision { ... }),
    6 => Ok(MappingKind::MCDCBranch { ... }),
    _ => Err(anyhow!("unknown mapping kind: {raw_mapping_kind:#x}")),
}

// after (add the new LLVM mapping kind, e.g. discriminant 7)
    7 => Ok(MappingKind::NewKind { ... }),
    _ => Err(anyhow!("unknown mapping kind: {raw_mapping_kind:#x}")),
Defensive patterns

Strategy: try-catch

Validate before calling

// No general caller-side validation is possible for opaque ULEB128 discriminants.
// Ensure producer/dumper LLVM versions match before dumping.

Try / catch

if let Err(e) = dump_covfun_mappings(llvm_ir, &filename_tables, &function_names) {
    if let Some(m) = e.to_string().strip_prefix("unknown mapping kind: ") {
        eprintln!("Unrecognized mapping kind {m}; update coverage-dump for this LLVM version.");
    }
    return Err(e);
}

Prevention

When it happens

Trigger: An LLVM version introduced a new mapping kind whose discriminant is not yet recognized by coverage-dump; the coverage payload is corrupted or misaligned so a ULEB128 read consumes the wrong bytes; version skew between producer and dumper.

Common situations: Upgrading LLVM added a new mapping variant; reading a covfun payload from a different/older format; byte-level corruption of the __llvm_covfun section.

Related errors

AI-assisted analysis of rust-lang/rust@7088e4b63a (2026-08-10). Data as JSON: /api/errors/8b59acff7644259d. Report an issue: GitHub.