EllanJiang/GameFramework · error · GameFrameworkException

Can not load asset ' ' which is a binary asset.

Error message

Can not load asset '{0}' which is a binary asset.

What it means

LoadAsset found the asset in the resource info table but it is marked as loaded from binary; binary resources cannot be loaded as assets, and with no failure callback registered the error is thrown. Binary assets must be loaded through the binary APIs instead.

Solutions

  1. Use LoadBinary (or the binary load API) for binary resources instead of LoadAsset.
  2. Fix the resource build configuration so the asset is packaged as an asset, not binary.
  3. Pass a failure callback to handle the error gracefully.
  4. Verify the asset name resolves to the intended asset, not a similarly named binary resource.

Example fix

// before
var bin = resourceComponent.LoadAsset("Configs/data", typeof(object), callbacks);
// after
byte[] bytes = resourceComponent.LoadBinary("Configs/data");
Defensive patterns

Strategy: validation

Validate before calling

// Load binary resources through LoadBinary instead
byte[] data = resourceComponent.LoadBinary(resourceName);

Try / catch

try { resourceComponent.LoadAsset(name, type, callbacksWithTypeError); }
catch (GameFrameworkException ex) { Log.Error("Binary asset via LoadAsset: " + ex.Message); }

Prevention

When it happens

Trigger: Calling LoadAsset on an asset name whose resourceInfo.IsLoadFromBinary is true (e.g. a raw file/binary resource) while LoadAssetFailureCallback is null.

Common situations: Attempting to load non-asset raw files (config binaries, movies, textures packed as raw resources) through LoadAsset; misconfigured build rules that pack a serializable asset as binary.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

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

                    if (loadAssetCallbacks.LoadAssetFailureCallback != null)
                    {
                        loadAssetCallbacks.LoadAssetFailureCallback(assetName, resourceInfo != null && !resourceInfo.Ready ? LoadResourceStatus.NotReady : LoadResourceStatus.NotExist, errorMessage, userData);
                        return;
                    }

                    throw new GameFrameworkException(errorMessage);
                }

                if (resourceInfo.IsLoadFromBinary)
                {
                    string errorMessage = Utility.Text.Format("Can not load asset '{0}' which is a binary asset.", assetName);
                    if (loadAssetCallbacks.LoadAssetFailureCallback != null)
                    {
                        loadAssetCallbacks.LoadAssetFailureCallback(assetName, LoadResourceStatus.TypeError, errorMessage, userData);
                        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);
                    }
                }

View on GitHub (pinned to d0c010b051)