bevyengine/bevy · error · syn::Error

Cannot use scene assets without caching, please add the ':'

Error message

Cannot use scene assets without caching, please add the ':' prefix.

What it means

BsnScene::parse requires the inverse too: when the entry is a string literal (the scene-asset form, BsnScene::Asset), a ':' cache prefix MUST be present. A bare "scene.glb#Scene0" without ':' produces this compile-time error, because scene assets are only usable through the cached form.

Source

Thrown at crates/bevy_scene/macros/src/bsn/parse.rs:236

                Err(syn::Error::new(colon.span(), msg))
            } else {
                Ok(())
            }
        };

        // It may seem odd how this is checking LitStr again
        // and how there doesn't seem to be a need for all the specific `err_if_cached`
        // in later code. But since caching is planned, and will very likely
        // have the limitations which are ensured by the other errors below,
        // this is its own block so its very simple to remove once caching is implemented.
        if !input.peek(LitStr) {
            err_if_cached("Currently, caching is only supported for scene assets. Please remove the ':' prefix for now.")?;
        }

        Ok(if input.peek(LitStr) {
            let path = input.parse::<LitStr>()?;
            if cached.is_none() {
                return Err(syn::Error::new(
                    path.span(),
                    "Cannot use scene assets without caching, please add the ':' prefix.",
                ));
            }
            BsnScene::Asset(path)
        } else if input.peek(Brace) {
            err_if_cached("Cannot cache scene expressions")?;
            BsnScene::Expression(braced_tokens(input)?)
        } else if input.peek(At) {
            input.parse::<At>()?;
            let sc = input.parse::<BsnType>()?;
            if sc.fields.len() > 0 {
                err_if_cached("Cannot cache Scene Components with props/fields")?;
            }
            BsnScene::SceneComponent(sc)
        } else {
            // PERF: do we really need this fork here?
            let path = input.fork().parse::<Path>()?;

View on GitHub (pinned to 396ca72708)

Solutions

Add the ':' prefix in front of the string literal: :"model.glb#Scene1"
Keep the entry as the FIRST entry of the list, since cached entries may not come after other entries

Example fix

// before
bsn!("model.glb#Scene1", MyComponent);

// after
bsn!(:"model.glb#Scene1", MyComponent);

Defensive patterns

Strategy: validation

Validate before calling

// Rule to enforce before writing BSN: every string-literal scene path
// must be preceded by ':' (and placed first in its entry list).

Prevention

Always write scene assets as :"path#SceneId", never as bare strings
Place the cached asset entry first in the list to also satisfy the first-entry rule

When it happens

Trigger: Writing bsn!("model.glb#Scene1") or an entry list containing an unprefixed string-literal scene path.

Common situations: Muscle memory from other Bevy macros where asset paths are bare strings; upgrading projects to the BSN syntax where the ':' prefix is mandatory; forgetting the prefix when adding a scene asset entry.

Related errors

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