bevyengine/bevy · error

{derive} derive expected named structs with a single field o

Error message

{derive} derive expected named structs with a single field or with a field annotated with #[relationship].

What it means

Compile error from relationship_field: the derive was applied to a named struct with multiple fields, and none of them carries the #[relationship] attribute, so the helper cannot determine which field stores the related Entity. The span passed in (usually the struct or derive span) anchors this generic validation guard.

Source

Thrown at crates/bevy_ecs/macro_logic/src/component.rs:806

        })
    }
}

/// Returns the field with the `#[relationship]` attribute, the only field if unnamed,
/// or the only field in a [`Fields::Named`] with one field, otherwise `Err`.
pub(crate) fn relationship_field<'a>(
    fields: &'a Fields,
    derive: &'static str,
    span: Span,
) -> Result<&'a Field> {
    match fields {
        Fields::Named(fields) if fields.named.len() == 1 => Ok(fields.named.first().unwrap()),
        Fields::Named(fields) => fields.named.iter().find(|field| {
            field
                .attrs
                .iter()
                .any(|attr| attr.path().is_ident(RELATIONSHIP))
        }).ok_or(syn::Error::new(
            span,
            format!("{derive} derive expected named structs with a single field or with a field annotated with #[relationship].")
        )),
        Fields::Unnamed(fields) if fields.unnamed.len() == 1 => Ok(fields.unnamed.first().unwrap()),
        Fields::Unnamed(fields) => fields.unnamed.iter().find(|field| {
                field
                    .attrs
                    .iter()
                    .any(|attr| attr.path().is_ident(RELATIONSHIP))
            })
            .ok_or(syn::Error::new(
                span,
                format!("{derive} derive expected unnamed structs with one field or with a field annotated with #[relationship]."),
            )),
        Fields::Unit => Err(syn::Error::new(
            span,
            format!("{derive} derive expected named or unnamed struct, found unit struct."),
        )),

View on GitHub (pinned to 396ca72708)

Solutions

1. Annotate exactly one field with #[relationship], e.g. #[relationship] pub target: Entity
2. Reduce the named struct to a single field so it is used unambiguously
3. Use a tuple struct with one field: struct ChildOf(Entity);

When it happens

Trigger: Thrown at crates/bevy_ecs/macro_logic/src/component.rs:806 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/2f448e1c9f900062. Report an issue: GitHub.