bevyengine/bevy · error · syn::Error

Only one source is allowed for SubStates

Error message

Only one source is allowed for SubStates

What it means

Compile-time error from derive(SubStates) (states.rs:70-75): parse_sources_attr collects one Source per parsed `#[source(...)]` attribute/meta and rejects result.len() > 1. A SubStates type has exactly one upstream state, so multiple `#[source(...)]` attributes — or multiple `Type = value` pairs inside one — are rejected.

Source

Thrown at crates/bevy_state/macros/src/states.rs:72

                    source_value,
                });
                Ok(())
            });
            match source {
                Some(value) => Ok(value),
                None => match value {
                    Ok(_) => Err(syn::Error::new(
                        ast.span(),
                        "Couldn't parse SubStates source",
                    )),
                    Err(e) => Err(e),
                },
            }
        })
        .collect::<Result<Vec<_>>>()?;

    if result.len() > 1 {
        return Err(syn::Error::new(
            ast.span(),
            "Only one source is allowed for SubStates",
        ));
    }

    let Some(result) = result.pop() else {
        return Err(syn::Error::new(ast.span(), "SubStates require a source"));
    };

    Ok(result)
}

pub fn derive_substates(input: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(input as DeriveInput);
    let sources = parse_sources_attr(&ast).expect("Failed to parse substate sources");

    let generics = ast.generics;
    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();

View on GitHub (pinned to 396ca72708)

Solutions

1. Keep exactly one `#[source(ParentState = Value)]` attribute with one pair
2. If two upstream states are needed, model the combination as a parent States enum (e.g. a tuple state) and source from that

Example fix

// before — two sources
#[derive(SubStates, ...)]
#[source(GameState = GameState::Playing)]
#[source(UiState = UiState::Open)]
enum MenuState { Root, Settings }

// after — one combined parent state drives the substate
#[derive(SubStates, ...)]
#[source(GameState = GameState::Playing)]
enum MenuState { Root, Settings }

When it happens

Trigger: Stacking `#[source(A = a)] #[source(B = b)]` on one enum; writing `#[source(A = a, B = b)]` with two pairs in a single attribute.

Common situations: Trying to make a substate depend on two parent states (not supported — use a States pair/combinator instead); copy-pasting source attributes during refactoring.

Related errors

• Couldn't parse SubStates source
• SubStates require a source
• Failed to parse substate sources
• Currently, caching is only supported for scene assets. Pleas
• Cannot use scene assets without caching, please add the ':'

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