EllanJiang/GameFramework · error · GameFrameworkException

Can not load dependency asset

Error message

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

What it means

While queueing LoadAsset, one of the asset's dependency assets failed to load (LoadDependencyAsset returned false) and no failure callback was set, so the formatted error is thrown. The main asset cannot be loaded without its dependencies.

Solutions

  1. Rebuild/re-download resource packages so all dependency assets are present.
  2. Check the dependency error message to identify the missing dependency asset.
  3. Verify resource version currency (check version / update resources before loading).
  4. Provide a failure callback to receive LoadResourceStatus.DependencyError instead of an exception.

Example fix

// before
resourceComponent.LoadAsset(name, type, null);
// after
resourceComponent.LoadAsset(name, type, new LoadAssetCallbacks(onSuccess,
    (n, status, msg, ud) => Log.Error($"Dependency load failed for {n}: {msg}")));
Defensive patterns

Strategy: try-catch

Validate before calling

// Precheck dependencies are in the catalog
foreach (var dep in dependencyNames)
    if (!resourceComponent.HasAsset(dep)) Log.Warning("Missing dependency: " + dep);

Try / catch

try { resourceComponent.LoadAsset(name, type, new LoadAssetCallbacks(onSuccess,
    (n, s, m, u) => { if (s == LoadResourceStatus.DependencyError) Log.Error($"Missing dependency: {m}"); })); }
catch (GameFrameworkException ex) { Log.Error(ex.Message); }

Prevention

When it happens

Trigger: LoadAsset is called, the main task is created, but a dependency asset name has no valid resource info or is a binary/missing resource, with LoadAssetFailureCallback null.

Common situations: Incomplete resource package missing dependency assets, stale resource version after a content update, editor-vs-build dependency mismatch, or manually edited asset names.

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/667b5127bdb4e0b8. Report an issue: GitHub.

Appendix: source

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

                        return;
                    }

                    throw new GameFrameworkException(errorMessage);
                }

                LoadAssetTask mainTask = LoadAssetTask.Create(assetName, assetType, priority, resourceInfo, dependencyAssetNames, loadAssetCallbacks, 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 asset '{1}'.", dependencyAssetName, assetName);
                        if (loadAssetCallbacks.LoadAssetFailureCallback != null)
                        {
                            loadAssetCallbacks.LoadAssetFailureCallback(assetName, 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="asset">要卸载的资源。</param>
            public void UnloadAsset(object asset)
            {
                m_AssetPool.Unspawn(asset);
            }

View on GitHub (pinned to d0c010b051)