EllanJiang/GameFramework · error · GameFrameworkException

Scene asset ' ' is being unloaded.

Error message

Scene asset '{0}' is being unloaded.

What it means

LoadScene throws this formatted error when the requested scene is currently being unloaded (SceneIsUnloading returns true). Concurrently loading a scene that is mid-unload is an invalid state for the scene module, which tracks loads and unloads in separate sets.

Solutions

1. Wait for the unload to finish (subscribe to LoadSceneUpdate/UnloadSceneComplete or check SceneIsUnloading in a loop/state) before loading again
2. Debounce/deduplicate LoadScene requests for the same asset name
3. Route scene transitions through a single procedure/state that serializes load and unload operations

Example fix

// before
m_SceneManager.LoadScene(sceneAssetName);
// after
if (m_SceneManager.SceneIsUnloading(sceneAssetName))
{
    // defer: retry when UnloadSceneComplete fires
    return;
}
m_SceneManager.LoadScene(sceneAssetName);

if (sceneManager.SceneIsUnloading(sceneAssetName)) { deferLoadUntilUnloadComplete(); return; }

bool IsSceneLoadable(SceneManager sm, string name) => !sm.SceneIsUnloading(name) && !sm.SceneIsLoading(name) && !sm.SceneIsLoaded(name);

try { sceneManager.LoadScene(name); } catch (GameFrameworkException ex) when (ex.Message.Contains("being unloaded")) { pendingSceneLoad = name; }

When it happens

Trigger: Calling LoadScene for an asset name that appears in the unloading set — e.g. rapidly switching back to a scene right after UnloadScene, or two systems triggering load/unload of the same scene concurrently.

Common situations: Fast scene switching where the player re-enters the previous scene before its unload completes; duplicate LoadScene calls from multiple procedures responding to the same event.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Results is invalid.
• Scene asset ' ' is being loaded.
• Scene asset name is invalid.
• You can not verify resources at this time.
• You must set resource manager first.

AI-assisted analysis of EllanJiang/GameFramework@d0c010b051 (2026-09-15). Data as JSON: /api/errors/581566877d44fcb8. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/Scene/SceneManager.cs:373

        /// </summary>
        /// <param name="sceneAssetName">场景资源名称。</param>
        /// <param name="priority">加载场景资源的优先级。</param>
        /// <param name="userData">用户自定义数据。</param>
        public void LoadScene(string sceneAssetName, int priority, object userData)
        {
            if (string.IsNullOrEmpty(sceneAssetName))
            {
                throw new GameFrameworkException("Scene asset name is invalid.");
            }

            if (m_ResourceManager == null)
            {
                throw new GameFrameworkException("You must set resource manager first.");
            }

            if (SceneIsUnloading(sceneAssetName))
            {
                throw new GameFrameworkException(Utility.Text.Format("Scene asset '{0}' is being unloaded.", sceneAssetName));
            }

            if (SceneIsLoading(sceneAssetName))
            {
                throw new GameFrameworkException(Utility.Text.Format("Scene asset '{0}' is being loaded.", sceneAssetName));
            }

            if (SceneIsLoaded(sceneAssetName))
            {
                throw new GameFrameworkException(Utility.Text.Format("Scene asset '{0}' is already loaded.", sceneAssetName));
            }

            m_LoadingSceneAssetNames.Add(sceneAssetName);
            m_ResourceManager.LoadScene(sceneAssetName, priority, m_LoadSceneCallbacks, userData);
        }

        /// <summary>
        /// 卸载场景。

View on GitHub (pinned to d0c010b051)