bevyengine/bevy · error

deriving {deref_kind} on multi-field structs requires one fi

Error message

deriving {deref_kind} on multi-field structs requires one field to have the {deref_attr_str} attribute

What it means

Compile-time syn error from get_deref_field: the struct has multiple fields but none is marked with the #[deref] attribute, so the derive cannot decide which field is the Deref/DerefMut target. Exactly one field must be annotated on multi-field structs.

Source

Thrown at crates/bevy_derive/src/derefs.rs:94

                    if selected_field.is_some() {
                        return Err(syn::Error::new_spanned(
                            attr,
                            format!(
                                "{deref_attr_str} attribute can only be used on a single field"
                            ),
                        ));
                    }

                    let member = to_member(field, index);
                    selected_field = Some((member, &field.ty));
                }
            }

            if let Some(selected_field) = selected_field {
                Ok(selected_field)
            } else {
                Err(syn::Error::new(
                    Span::call_site().into(),
                    format!("deriving {deref_kind} on multi-field structs requires one field to have the {deref_attr_str} attribute"),
                ))
            }
        }
        _ => Err(syn::Error::new(
            Span::call_site().into(),
            format!("{deref_kind} can only be derived on structs"),
        )),
    }
}

fn to_member(field: &Field, index: usize) -> Member {
    field
        .ident
        .as_ref()
        .map(|name| Member::Named(name.clone()))
        .unwrap_or_else(|| Member::Unnamed(Index::from(index)))

View on GitHub (pinned to 396ca72708)

Solutions

1. Add #[deref] to exactly one field of the struct
2. Reduce the struct to a single field so no annotation is needed

When it happens

Trigger: Thrown at crates/bevy_derive/src/derefs.rs:94 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of bevyengine/bevy@396ca72708 (2026-08-20). Data as JSON: /api/errors/b443ca63a8d74b89. Report an issue: GitHub.