bevyengine/bevy · error · syn::Error

Couldn't parse SubStates source

Error message

Couldn't parse SubStates source

What it means

Compile-time error from the derive(SubStates) proc macro (bevy_state/macros/src/states.rs:44-65). Source attributes are parsed with parse_nested_meta expecting `#[source(SourceStateType = pattern)]`; if attribute parsing succeeded but no valid source pair was captured (source stayed None while the meta parse returned Ok), the macro reports 'Couldn't parse SubStates source' on the whole derive.

Source

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

    let mut result = ast
        .attrs
        .iter()
        .filter(|a| a.path().is_ident("source"))
        .map(|meta| {
            let mut source = None;
            let value = meta.parse_nested_meta(|nested| {
                let source_type = nested.path.clone();
                let source_value = Pat::parse_multi(nested.value()?)?;
                source = Some(Source {
                    source_type,
                    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"));

View on GitHub (pinned to 396ca72708)

Solutions

1. Use the exact form `#[source(AppState = AppState::InGame)]` above the enum
2. Remember the shape is `SourceStateType = Pattern`, not a bare path or string
3. Check the SubStates documentation example for the current Bevy version

Example fix

// before
#[derive(SubStates, Debug, Hash, PartialEq, Eq, Clone)]
#[source]
enum MenuState { MainMenu, Paused }

// after
#[derive(SubStates, Debug, Hash, PartialEq, Eq, Clone)]
#[source(AppState = AppState::InGame)]
enum MenuState { MainMenu, Paused }

When it happens

Trigger: Writing `#[derive(SubStates)] #[source]` with no payload; `#[source(foo)]` where foo is not a `Type = value` pair; putting the source in an attribute the macro does not inspect.

Common situations: First use of SubStates following examples that omit the exact attribute shape; refactoring States into SubStates and leaving a bare marker attribute; typos in the attribute name so it is ignored.

Related errors

• Only one source is allowed for SubStates
• 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/4619dcca2eca2cb2. Report an issue: GitHub.