EllanJiang/GameFramework · error · GameFrameworkException

Unload scene failure, scene asset name

Error message

Unload scene failure, scene asset name '{0}'.

What it means

UnloadSceneFailureCallback fires when the resource layer reports a scene unload failure. If no UnloadSceneFailure event handler is registered, the framework throws this GameFrameworkException naming the scene that could not be unloaded.

Solutions

1. Subscribe to SceneManager.UnloadSceneFailure so failures arrive as events rather than exceptions.
2. Inspect the resource manager's diagnostics for the root cause of the failed unload.
3. Verify the scene was still valid/loaded at the time the unload was dispatched to the resource layer.
4. Re-check state (SceneIsLoaded/SceneIsUnloading) and retry the unload if transient.

Example fix

// before
m_SceneManager.UnloadScene(sceneName);
// after
m_SceneManager.UnloadSceneFailure += (sender, e) => Log.Error("Unload scene failed: {0}", e.SceneAssetName);
m_SceneManager.UnloadScene(sceneName);

try { sceneManager.UnloadScene(sceneAssetName); }
catch (GameFrameworkException ex) { Log.Error("Scene unload failed: {0}", ex.Message); }

When it happens

Trigger: An asynchronous scene unload fails at the resource layer while m_UnloadSceneFailureEventHandler is null (UnloadSceneFailure never subscribed).

Common situations: Resource subsystem errors during unload (destroyed scene, invalid resource state); forgetting to subscribe to UnloadSceneFailure; unload failures after forceful scene teardown or editor play-mode interruptions.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• appendErrorMessage
• Scene asset ' ' is already loaded.
• Scene asset ' ' is not loaded yet.
• Access is invalid.
• Already exist data table

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

Appendix: source

Thrown at GameFramework/Scene/SceneManager.cs:505

            {
                UnloadSceneSuccessEventArgs unloadSceneSuccessEventArgs = UnloadSceneSuccessEventArgs.Create(sceneAssetName, userData);
                m_UnloadSceneSuccessEventHandler(this, unloadSceneSuccessEventArgs);
                ReferencePool.Release(unloadSceneSuccessEventArgs);
            }
        }

        private void UnloadSceneFailureCallback(string sceneAssetName, object userData)
        {
            m_UnloadingSceneAssetNames.Remove(sceneAssetName);
            if (m_UnloadSceneFailureEventHandler != null)
            {
                UnloadSceneFailureEventArgs unloadSceneFailureEventArgs = UnloadSceneFailureEventArgs.Create(sceneAssetName, userData);
                m_UnloadSceneFailureEventHandler(this, unloadSceneFailureEventArgs);
                ReferencePool.Release(unloadSceneFailureEventArgs);
                return;
            }

            throw new GameFrameworkException(Utility.Text.Format("Unload scene failure, scene asset name '{0}'.", sceneAssetName));
        }
    }
}

View on GitHub (pinned to d0c010b051)