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

Item requires monomorphization

Error message

Item requires monomorphization

What it means

Thrown by the `TryFrom<CrateItem> for Instance` impl in compiler/rustc_public/src/mir/mono.rs:221 when the crate item has generic parameters that have not been substituted. An `Instance` is a fully concrete (monomorphized) code item, so a generic `fn foo<T>` or generic inherent/impl item cannot become an instance without first choosing concrete generic args. rustc_public surfaces this because it only hands out instances for items whose `requires_monomorphization` query returns false.

Source

Thrown at compiler/rustc_public/src/mir/mono.rs:221

            .field("kind", &self.kind)
            .field("def", &self.mangled_name())
            .field("args", &self.args())
            .finish()
    }
}

/// Try to convert a crate item into an instance.
/// The item cannot be generic in order to be converted into an instance.
impl TryFrom<CrateItem> for Instance {
    type Error = crate::Error;

    fn try_from(item: CrateItem) -> Result<Self, Self::Error> {
        with(|context| {
            let def_id = item.def_id();
            if !context.requires_monomorphization(def_id) {
                Ok(context.mono_instance(def_id))
            } else {
                Err(bridge::Error::new("Item requires monomorphization".to_string()))
            }
        })
    }
}

/// Try to convert an instance into a crate item.
/// Only user defined instances can be converted.
impl TryFrom<Instance> for CrateItem {
    type Error = crate::Error;

    fn try_from(value: Instance) -> Result<Self, Self::Error> {
        with(|context| {
            if value.kind == InstanceKind::Item && context.has_body(value.def.def_id()) {
                Ok(CrateItem(context.instance_def_id(value.def)))
            } else {
                Err(bridge::Error::new(format!("Item kind `{:?}` cannot be converted", value.kind)))
            }
        })

View on GitHub (pinned to 22057b88b0)

Solutions

  1. Filter items before conversion: call `context.requires_monomorphization(def_id)` and only call `Instance::try_from` when it returns false.
  2. If you need a concrete instance of a generic item, build it with explicit generic args via the context's instance-with-args API instead of the bare `TryFrom`.
  3. Handle the `Err` from `try_from` as a non-fatal skip rather than unwrapping, so generic items are skipped during a whole-crate walk.

Example fix

// before
for item in context.crate_items() {
    let instance = Instance::try_from(item)?;
    process(instance);
}
// after
for item in context.crate_items() {
    if context.requires_monomorphization(item.def_id()) {
        continue;
    }
    let instance = Instance::try_from(item)?;
    process(instance);
}
Defensive patterns

Strategy: validation

Validate before calling

// Before Instance::try_from(item):
if item.requires_monomorphization() {
    // item is generic (or lives in a generic impl); it cannot become a
    // monomorphic Instance without explicit args. Skip or resolve via
    // Instance::resolve(FnDef, &GenericArgs) instead.
    return Err(format!("item {:?} requires monomorphization", item));
}
let instance = Instance::try_from(item)?;

Type guard

// True only for non-generic CrateItems that yield a concrete Instance.
fn is_monomorphic_item(item: &CrateItem) -> bool {
    !item.requires_monomorphization()
}

Try / catch

// Instance::try_from returns Result; treat the Err as "needs args":
match Instance::try_from(item) {
    Ok(inst) => inst,
    Err(e) if e.to_string().contains("monomorphization") => {
        // Resolve with explicit generic args instead of TryFrom.
        return resolve_with_args(item)?;
    }
    Err(e) => return Err(e.into()),
}

Prevention

When it happens

Trigger: Calling `Instance::try_from(crate_item)` (or `.into()`) on a `CrateItem` whose DefId refers to a generic function/type/impl. Iterating `context.crate_items()` and converting each item unconditionally to an `Instance`. Passing a DefId resolved from a generic definition straight into instance construction without substituting args.

Common situations: Static analyzers/linters that walk every item in a crate and assume all are monomorphizable. Using a DefId lookup (e.g. by path) that returns a generic function. Migrating from a version where the item was monomorphic to one where it became generic.

Related errors

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