EllanJiang/GameFramework · error · GameFrameworkException

Binary asset name is invalid.

Error message

Binary asset name is invalid.

What it means

ResourceManager.GetBinaryPath validates binaryAssetName and throws this GameFrameworkException when it is null or empty. This method resolves the on-disk path of a binary resource (only applicable when binaries are stored on disk rather than packed file systems); an empty name cannot be resolved. The check precedes delegation to m_ResourceLoader.GetBinaryPath.

Solutions

  1. Pass the correct non-empty binary asset name
  2. Validate the name source (config, UI, computed path) for empty values before the call
  3. Remember GetBinaryPath only returns a real path for disk-stored binaries; if you actually want content, use LoadBinary instead

Example fix

// before
string path = resourceManager.GetBinaryPath(binaryName);
// after
if (string.IsNullOrEmpty(binaryName)) throw new ArgumentException("binaryName required");
string path = resourceManager.GetBinaryPath(binaryName);
Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrEmpty(binaryAssetName)) throw new ArgumentException("binaryAssetName required", nameof(binaryAssetName));

Try / catch

try { string path = resourceManager.GetBinaryPath(binaryAssetName); } catch (GameFrameworkException ex) { Log.Error(ex.Message); }

Prevention

When it happens

Trigger: Calling GetBinaryPath(string) with binaryAssetName null or "".

Common situations: Looking up a binary path before a load where the name variable was never assigned; config-driven binary asset lists with empty entries; path-building code that produced an empty string due to a failed format/combine.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at GameFramework/Resource/ResourceManager.cs:1784

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

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

        /// <summary>
        /// 获取二进制资源的实际路径。
        /// </summary>
        /// <param name="binaryAssetName">要获取实际路径的二进制资源的名称。</param>
        /// <returns>二进制资源的实际路径。</returns>
        /// <remarks>此方法仅适用于二进制资源存储在磁盘（而非文件系统）中的情况。若二进制资源存储在文件系统中时，返回值将始终为空。</remarks>
        public string GetBinaryPath(string binaryAssetName)
        {
            if (string.IsNullOrEmpty(binaryAssetName))
            {
                throw new GameFrameworkException("Binary asset name is invalid.");
            }

            return m_ResourceLoader.GetBinaryPath(binaryAssetName);
        }

        /// <summary>
        /// 获取二进制资源的实际路径。
        /// </summary>
        /// <param name="binaryAssetName">要获取实际路径的二进制资源的名称。</param>
        /// <param name="storageInReadOnly">二进制资源是否存储在只读区中。</param>
        /// <param name="storageInFileSystem">二进制资源是否存储在文件系统中。</param>
        /// <param name="relativePath">二进制资源或存储二进制资源的文件系统，相对于只读区或者读写区的相对路径。</param>
        /// <param name="fileName">若二进制资源存储在文件系统中，则指示二进制资源在文件系统中的名称，否则此参数返回空。</param>
        /// <returns>是否获取二进制资源的实际路径成功。</returns>
        public bool GetBinaryPath(string binaryAssetName, out bool storageInReadOnly, out bool storageInFileSystem, out string relativePath, out string fileName)
        {
            return m_ResourceLoader.GetBinaryPath(binaryAssetName, out storageInReadOnly, out storageInFileSystem, out relativePath, out fileName);
        }

View on GitHub (pinned to d0c010b051)