bevyengine/bevy · error

Missing `relationship = X` attribute

Error message

Missing `relationship = X` attribute

What it means

Compile error from parsing #[relationship] attribute options in the Relationship derive macro: after the `relationship` keyword the parser could not consume the required `= X` (the relationship-target type) or encountered an unknown option token, so syn's lookahead1 produced this generic error naming the offending input.

Source

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

        while !input.is_empty() {
            let lookahead = input.lookahead1();
            if lookahead.peek(kw::linked_spawn) {
                input.parse::<kw::linked_spawn>()?;
                linked_spawn = true;
            } else if lookahead.peek(kw::relationship) {
                input.parse::<kw::relationship>()?;
                input.parse::<Token![=]>()?;
                relationship = Some(input.parse()?);
            } else {
                return Err(lookahead.error());
            }
            if !input.is_empty() {
                input.parse::<Token![,]>()?;
            }
        }
        Ok(RelationshipTarget {
            relationship: relationship.ok_or_else(|| {
                syn::Error::new(input.span(), "Missing `relationship = X` attribute")
            })?,
            linked_spawn,
        })
    }
}

/// 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

View on GitHub (pinned to 396ca72708)

Solutions

1. Write the attribute as #[relationship = TargetType] with an explicit equals sign and type path
2. Check for typos in option keywords (only relationship and linked_spawn are accepted here)
3. Delimit multiple options with commas: #[relationship = Target, linked_spawn)]

When it happens

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