EllanJiang/GameFramework · error · GameFrameworkException

Can not load dependency asset

Error message

Can not load dependency asset '{0}' when load scene '{1}'.

What it means

Thrown by ResourceLoader.LoadScene when LoadDependencyAsset fails for one of the scene's dependency assets. A scene cannot be loaded until every dependency loads, so the whole LoadScene call aborts synchronously with the failing dependency name and scene name in the message.

Solutions

  1. Rebuild or re-download resource packages so scene dependencies are present.
  2. Check the error message to identify the failing dependency asset.
  3. Update to the correct resource version before loading the scene.
  4. Pass LoadSceneCallbacks with a failure callback to receive DependencyError status instead of a throw.

Example fix

// before
resourceComponent.LoadScene(sceneName, priority, null);
// after
resourceComponent.LoadScene(sceneName, priority, new LoadSceneCallbacks(onLoaded,
    (n, s, m, u) => Log.Error($"Scene {n} dependency error: {m}")));
Defensive patterns

Strategy: try-catch

Validate before calling

foreach (var dep in dependencyNames)
    if (!resourceComponent.HasAsset(dep)) Log.Warning("Scene dependency missing: " + dep);

Try / catch

try { resourceComponent.LoadScene(sceneName, priority, new LoadSceneCallbacks(onLoaded,
    (n, s, m, u) => Log.Error($"Scene dependency failed: {m}"))); }
catch (GameFrameworkException ex) { Log.Error(ex.Message); }

Prevention

When it happens

Trigger: LoadScene creates the main task, then LoadDependencyAsset fails for a dependency (missing/invalid resource info or binary) with LoadSceneFailureCallback null.

Common situations: Resource package missing dependency assets for the scene, outdated resource version, dependencies removed in a build, or corrupted resource tables.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at GameFramework/Resource/ResourceManager.ResourceLoader.cs:413

                        return;
                    }

                    throw new GameFrameworkException(errorMessage);
                }

                LoadSceneTask mainTask = LoadSceneTask.Create(sceneAssetName, priority, resourceInfo, dependencyAssetNames, loadSceneCallbacks, userData);
                foreach (string dependencyAssetName in dependencyAssetNames)
                {
                    if (!LoadDependencyAsset(dependencyAssetName, priority, mainTask, userData))
                    {
                        string errorMessage = Utility.Text.Format("Can not load dependency asset '{0}' when load scene '{1}'.", dependencyAssetName, sceneAssetName);
                        if (loadSceneCallbacks.LoadSceneFailureCallback != null)
                        {
                            loadSceneCallbacks.LoadSceneFailureCallback(sceneAssetName, LoadResourceStatus.DependencyError, errorMessage, userData);
                            return;
                        }

                        throw new GameFrameworkException(errorMessage);
                    }
                }

                m_TaskPool.AddTask(mainTask);
                if (!resourceInfo.Ready)
                {
                    m_ResourceManager.UpdateResource(resourceInfo.ResourceName);
                }
            }

            /// <summary>
            /// 异步卸载场景。
            /// </summary>
            /// <param name="sceneAssetName">要卸载场景资源的名称。</param>
            /// <param name="unloadSceneCallbacks">卸载场景回调函数集。</param>
            /// <param name="userData">用户自定义数据。</param>
            public void UnloadScene(string sceneAssetName, UnloadSceneCallbacks unloadSceneCallbacks, object userData)
            {

View on GitHub (pinned to d0c010b051)