Fix failed sub-asset loads getting stuck in `LoadState::Loading` by greeble-dev · Pull Request #22628 · bevyengine/bevy

greeble-dev · 2026-01-21T17:16:05Z

Objective

Fix #22607. Also add a test that reproduces the issues.

If it makes things clearer, I can split this into an "add a test" PR and a separate "fix the bug" PR.

Solution

There are three additions to AssetServer::load_internal that each fix a separate case. In source code order:

Case 1

// Sub-asset exists, but is not of type `WrongAssetType`.
asset_server.load::<WrongAssetType>("asset#subasset");

Previously this would silently fail - the asset would successfully load, but the handle can't actually resolve to that asset so it's stuck in limbo.

Fixed by adding a type check, then sending a AssetLoadError::RequestedHandleTypeMismatch event and returning it as an error.

Note that this doesn't prevent someone loading the asset with the correct type - the error is only associated with the <WrongAssetType> handle.

Case 2

// Sub-asset doesn't exist.
asset_server.load::<AssetType>("asset#non_existent_subasset");

Previously this was detected and would return a AssetLoadError::MissingLabel error from load_internal, but the load status for the handle wasn't set.

Fixed by sending an InternalAssetEvent::Failed.

Case 3

// Asset loader returns an error.
asset_server.load::<AssetType>("malformed_asset#subasset");

Previously this was detected, but the event was sent with the root asset's id (base_asset_id) so it wasn't associated with the sub-asset's handle.

Fixed by using the sub-asset's id.

Notes

Some of the events are only sent if asset_id is set. This might seem odd, but I think it's correct - asset_id can only be unset when using load_untyped with a sub-asset path, in which case there's no handle to associate with the error, and so there's no handle to pass to get_load_status.

Testing

cargo test -p bevy_asset
cargo test -p bevy_asset --features "multi_threaded"

…ng type" test.

… least for the case where the sub-asset type is known.

…t is not of the requested type.

… requested type".

…a `AssetLoadError` variant.

…d was requested on the sub-asset. This meant the `LoadStatus` of the sub-asset would not reflect the error.

andriyDev · 2026-01-22T08:08:18Z

crates/bevy_asset/src/lib.rs

+        for _ in 0..LARGE_ITERATION_COUNT {
+            app.update();
+            load_state = asset_server.get_load_state(&handle).unwrap().into();
+            if load_state == expected_load_state {
+                break;
+            }
+        }


Should we just use run_app_until here instead?

I did this initially, but found that it made debugging test failures harder - run_app_until will panic without any information about what failed. Doing it manually lets me print a clear "did X, expected Y, got Z".

I do think there's room for improvement. Maybe adding a run_app_until variant with more options, or even better a way to say "run until all loads have resolved". But don't think that would fit in this PR.

) ## Objective Fix #22607. Also add a test that reproduces the issues. If it makes things clearer, I can split this into an "add a test" PR and a separate "fix the bug" PR. ## Solution There are three additions to `AssetServer::load_internal` that each fix a separate case. In source code order: ### Case 1 ```rust // Sub-asset exists, but is not of type `WrongAssetType`. asset_server.load::<WrongAssetType>("asset#subasset"); ``` Previously this would silently fail - the asset would successfully load, but the handle can't actually resolve to that asset so it's stuck in limbo. Fixed by adding a type check, then sending a `AssetLoadError::RequestedHandleTypeMismatch` event and returning it as an error. Note that this doesn't prevent someone loading the asset with the correct type - the error is only associated with the `<WrongAssetType>` handle. ### Case 2 ```rust // Sub-asset doesn't exist. asset_server.load::<AssetType>("asset#non_existent_subasset"); ``` Previously this was detected and would return a `AssetLoadError::MissingLabel` error from `load_internal`, but the load status for the handle wasn't set. Fixed by sending an `InternalAssetEvent::Failed`. ### Case 3 ```rust // Asset loader returns an error. asset_server.load::<AssetType>("malformed_asset#subasset"); ``` Previously this was detected, but the event was sent with the root asset's id (`base_asset_id`) so it wasn't associated with the sub-asset's handle. Fixed by using the sub-asset's id. ### Notes Some of the events are only sent if `asset_id` is set. This might seem odd, but I think it's correct - `asset_id` can only be unset when using `load_untyped` with a sub-asset path, in which case there's no handle to associate with the error, and so there's no handle to pass to `get_load_status`. ## Testing ```sh cargo test -p bevy_asset cargo test -p bevy_asset --features "multi_threaded" ```

…yengine#22628) ## Objective Fix bevyengine#22607. Also add a test that reproduces the issues. If it makes things clearer, I can split this into an "add a test" PR and a separate "fix the bug" PR. ## Solution There are three additions to `AssetServer::load_internal` that each fix a separate case. In source code order: ### Case 1 ```rust // Sub-asset exists, but is not of type `WrongAssetType`. asset_server.load::<WrongAssetType>("asset#subasset"); ``` Previously this would silently fail - the asset would successfully load, but the handle can't actually resolve to that asset so it's stuck in limbo. Fixed by adding a type check, then sending a `AssetLoadError::RequestedHandleTypeMismatch` event and returning it as an error. Note that this doesn't prevent someone loading the asset with the correct type - the error is only associated with the `<WrongAssetType>` handle. ### Case 2 ```rust // Sub-asset doesn't exist. asset_server.load::<AssetType>("asset#non_existent_subasset"); ``` Previously this was detected and would return a `AssetLoadError::MissingLabel` error from `load_internal`, but the load status for the handle wasn't set. Fixed by sending an `InternalAssetEvent::Failed`. ### Case 3 ```rust // Asset loader returns an error. asset_server.load::<AssetType>("malformed_asset#subasset"); ``` Previously this was detected, but the event was sent with the root asset's id (`base_asset_id`) so it wasn't associated with the sub-asset's handle. Fixed by using the sub-asset's id. ### Notes Some of the events are only sent if `asset_id` is set. This might seem odd, but I think it's correct - `asset_id` can only be unset when using `load_untyped` with a sub-asset path, in which case there's no handle to associate with the error, and so there's no handle to pass to `get_load_status`. ## Testing ```sh cargo test -p bevy_asset cargo test -p bevy_asset --features "multi_threaded" ```

greeble-dev added 9 commits January 20, 2026 08:52

First pass.

29f779b

Redid test as a simpler function. Fixed misleading "root asset is wro…

5241f1a

…ng type" test.

Fixed missing sub-asset errors failing to set LoadState::Failed, at…

a22ca54

… least for the case where the sub-asset type is known.

Fixed sub-assets getting stuck in the loading state when the sub-asse…

1295646

…t is not of the requested type.

Added tested for malformed root and sub-assets, and "sub-asset is not…

f8d3ceb

… requested type".

Added "sub-asset of root asset that does not exist" test.

35b6c0b

Improved legibility when TestAssetLoadError is lacking support for …

795363a

…a `AssetLoadError` variant.

Tidy ups.

6aedd51

Fixed loader error events getting sent to the root asset when the loa…

51f8ae3

…d was requested on the sub-asset. This meant the `LoadStatus` of the sub-asset would not reflect the error.

greeble-dev added C-Bug An unexpected or incorrect behavior A-Assets Load files from disk to use for things like images, models, and sounds labels Jan 21, 2026

alice-i-cecile requested a review from andriyDev January 21, 2026 17:29

greeble-dev added the S-Needs-Review Needs reviewer attention (from anyone!) to move forward label Jan 21, 2026

andriyDev approved these changes Jan 22, 2026

View reviewed changes

alice-i-cecile approved these changes Feb 2, 2026

View reviewed changes

alice-i-cecile added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Feb 2, 2026

alice-i-cecile added this pull request to the merge queue Feb 2, 2026

Merged via the queue into bevyengine:main with commit f929d06 Feb 2, 2026
47 checks passed

greeble-dev mentioned this pull request Feb 9, 2026

Do not unload subassets or the root asset unless all subassets and root asset handles have been dropped. #21878

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comments

Fix failed sub-asset loads getting stuck in `LoadState::Loading`#22628

Fix failed sub-asset loads getting stuck in `LoadState::Loading`#22628
alice-i-cecile merged 9 commits intobevyengine:mainfrom
greeble-dev:test-asset-load-fail

greeble-dev commented Jan 21, 2026 •

edited

Loading

Uh oh!

andriyDev Jan 22, 2026

Uh oh!

greeble-dev Jan 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Comments

Conversation

greeble-dev commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Case 1

Case 2

Case 3

Notes

Testing

Uh oh!

andriyDev Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

greeble-dev Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

greeble-dev commented Jan 21, 2026 •

edited

Loading