What causes "Unload scene callbacks is invalid." in EllanJiang/GameFramework?

Pass an initialized UnloadSceneCallbacks with the success and failure handlers

EllanJiang/GameFramework · error · GameFrameworkException

Unload scene callbacks is invalid.

Error message

Unload scene callbacks is invalid.

What it means

ResourceManager.UnloadScene(string, UnloadSceneCallbacks) validates unloadSceneCallbacks and throws this GameFrameworkException when it is null. Callbacks are required so the caller is informed when the scene unload completes or fails. The check occurs immediately before forwarding to m_ResourceLoader.UnloadScene with a null userData.

Solutions

Pass an initialized UnloadSceneCallbacks with the success and failure handlers
Provide no-op handlers if you do not care about the result
Fix wrapper methods to require or construct callbacks instead of forwarding null

Example fix

// before
resourceManager.UnloadScene(sceneAssetName, null);
// after
resourceManager.UnloadScene(sceneAssetName, new UnloadSceneCallbacks(
    onSuccess => { }, onFailure => { }));

Defensive patterns

Strategy: validation

Validate before calling

if (unloadSceneCallbacks == null) throw new ArgumentException("unloadSceneCallbacks required", nameof(unloadSceneCallbacks));

Type guard

bool HasUnloadCallbacks(UnloadSceneCallbacks? c) => c is not null;

Try / catch

try { resourceManager.UnloadScene(sceneAssetName, unloadCallbacks); } catch (GameFrameworkException ex) { Log.Error(ex.Message); }

Prevention

Construct UnloadSceneCallbacks with success and failure handlers
Do not attempt fire-and-forget unloads with null callbacks
Create a shared helper for unload callbacks to avoid repetition

When it happens

Trigger: Calling UnloadScene(sceneAssetName, unloadSceneCallbacks) with unloadSceneCallbacks == null.

Common situations: Fire-and-forget unload attempts passing null; unassigned callback field; helper APIs that wrap UnloadScene and drop the callbacks parameter.

Related errors

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

Appendix: source

Thrown at GameFramework/Resource/ResourceManager.cs:1747

            m_ResourceLoader.LoadScene(sceneAssetName, priority, loadSceneCallbacks, userData);
        }

        /// <summary>
        /// 异步卸载场景。
        /// </summary>
        /// <param name="sceneAssetName">要卸载场景资源的名称。</param>
        /// <param name="unloadSceneCallbacks">卸载场景回调函数集。</param>
        public void UnloadScene(string sceneAssetName, UnloadSceneCallbacks unloadSceneCallbacks)
        {
            if (string.IsNullOrEmpty(sceneAssetName))
            {
                throw new GameFrameworkException("Scene asset name is invalid.");
            }

            if (unloadSceneCallbacks == null)
            {
                throw new GameFrameworkException("Unload scene callbacks is invalid.");
            }

            m_ResourceLoader.UnloadScene(sceneAssetName, unloadSceneCallbacks, null);
        }

        /// <summary>
        /// 异步卸载场景。
        /// </summary>
        /// <param name="sceneAssetName">要卸载场景资源的名称。</param>
        /// <param name="unloadSceneCallbacks">卸载场景回调函数集。</param>
        /// <param name="userData">用户自定义数据。</param>
        public void UnloadScene(string sceneAssetName, UnloadSceneCallbacks unloadSceneCallbacks, object userData)
        {
            if (string.IsNullOrEmpty(sceneAssetName))
            {
                throw new GameFrameworkException("Scene asset name is invalid.");
            }

View on GitHub (pinned to d0c010b051)