rust-lang/cargo · error

must have the unit

Error message

must have the unit

What it means

Invariant in `cargo report rebuilds`. The code iterates `root_rebuilds` and looks each `unit_index` up in a `units` map via `units.get(&root_rebuild.unit_index).map(unit_description).expect("must have the unit")`. Every unit referenced by a rebuild entry must already exist in the units map built earlier in the report.

Source

Thrown at src/ops/cargo_report/rebuilds.rs:321

        DEFAULT_DISPLAY_LIMIT.min(root_rebuilds.len())
    };
    let truncated_count = root_rebuilds.len().saturating_sub(display_limit);

    if truncated_count > 0 {
        let count = root_rebuilds.len();
        writeln!(
            stderr,
            "{header}Root rebuilds:{header:#} (top {display_limit} of {count} by impact)",
        )?;
    } else {
        writeln!(stderr, "{header}Root rebuilds:{header:#}",)?;
    }

    for (idx, root_rebuild) in root_rebuilds.iter().take(display_limit).enumerate() {
        let unit_desc = units
            .get(&root_rebuild.unit_index)
            .map(unit_description)
            .expect("must have the unit");

        let reason_str = format_dirty_reason(&root_rebuild.reason, &units, ws_root);

        writeln!(
            stderr,
            "  {subheader}{idx}. {unit_desc}:{subheader:#} {reason_str}",
        )?;

        if root_rebuild.affected_units.is_empty() {
            writeln!(stderr, "     impact: no cascading rebuilds")?;
        } else {
            let count = root_rebuild.affected_units.len();
            let plural = plural(count);
            writeln!(
                stderr,
                "     impact: {count} dependent unit{plural} rebuilt"
            )?;

View on GitHub (pinned to 0e07a15537)

Solutions

1. Clear cargo's build cache (`cargo clean` and remove `target/`) and re-run the build + `cargo report rebuilds`.
2. Report a cargo bug with the `cargo report rebuilds -vv` output and the workspace manifest.
3. Update cargo — this is part of an evolving experimental feature and fixes land frequently.

// Before calling cargo report rebuilds, ensure every rebuild unit exists in the unit map.
for r in &root_rebuilds {
    if !units.contains_key(&r.unit_index) {
        return Err(anyhow!("rebuild references unknown unit {}", r.unit_index));
    }
}

When it happens

Trigger: Fires only if a `RootRebuild`'s `unit_index` is not present in the `units` map that `cargo report rebuilds` constructed from the build graph. This indicates the rebuild-analysis index and the unit map got out of sync.

Common situations: Cargo bug in the `cargo report` (future-build-report) experimental subcommand; mismatched index after a partial/aborted build-graph build; running an unreleased `cargo report` against a stale build cache.

Related errors

• artifact-dir was not locked
• artifact dep
• already loaded config values
• env var was not array
• was not filled at beginning of the function

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/3d15e688be15abaa.json. Report an issue: GitHub.