bevyengine/bevy · error

RelationshipTarget can only be derived for structs.

Error message

RelationshipTarget can only be derived for structs.

What it means

Compile-time error from derive_relationship_target: #[derive(RelationshipTarget)] was applied to an enum or union rather than a struct; the target derive needs a named struct field holding the linked-entity collection.

Source

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

        }))
    }

    fn derive_relationship_target(
        &self,
        ast: &DeriveInput,
        bevy_ecs: &Path,
    ) -> Result<Option<TokenStream>> {
        let Some(relationship_target) = &self.relationship_target else {
            return Ok(None);
        };

        let Data::Struct(DataStruct {
            fields,
            struct_token,
            ..
        }) = &ast.data
        else {
            return Err(syn::Error::new(
                ast.span(),
                "RelationshipTarget can only be derived for structs.",
            ));
        };
        let field = relationship_field(fields, "RelationshipTarget", struct_token.span())?;

        if field.vis != Visibility::Inherited {
            return Err(syn::Error::new(field.span(), "The collection in RelationshipTarget must be private to prevent users from directly mutating it, which could invalidate the correctness of relationships."));
        }
        let collection = &field.ty;
        let relationship_member = field.ident.clone().map_or(Member::from(0), Member::Named);

        let members = fields
            .members()
            .filter(|member| member != &relationship_member);

        let relationship = &relationship_target.relationship;
        let struct_name = &ast.ident;

View on GitHub (pinned to 396ca72708)

Solutions

1. Apply #[derive(RelationshipTarget)] only to structs
2. Wrap the collection in a newtype struct and derive on it

When it happens

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