bevyengine/bevy · error · syn::Error

SubStates require a source

Error message

SubStates require a source

What it means

Compile-time error from derive(SubStates) (states.rs:77-80): after dedup checks, result.pop() finds nothing, meaning the derive had no parseable `#[source(...)]` attribute at all. SubStates must declare which parent state and value they are derived from; a plain derive cannot generate that.

Source

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

                    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();

    let mut base_trait_path = bevy_state_path();
    base_trait_path.segments.push(format_ident!("state").into());

    let mut trait_path = base_trait_path.clone();
    trait_path.segments.push(format_ident!("SubStates").into());

View on GitHub (pinned to 396ca72708)

Solutions

1. Add `#[source(ParentStateType = ParentState::Variant)]` to the derived enum
2. Double-check the attribute spelling — anything other than `source` is silently ignored

Example fix

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

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

When it happens

Trigger: `#[derive(SubStates)]` on an enum with no `#[source]` attribute; the source attribute misspelled (e.g. `#[sources]`) so it is ignored.

Common situations: Converting a States enum to SubStates and deleting the attribute; upgrading from a Bevy version with different source syntax; attribute-name typos.

Related errors

• Couldn't parse SubStates source
• Only one source is allowed for SubStates
• 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/622e417fef83732d. Report an issue: GitHub.