EllanJiang/GameFramework · error · GameFrameworkException

File system helper is invalid.

Error message

File system helper is invalid.

What it means

FileSystemManager.SetFileSystemHelper stores the IFileSystemHelper used to create file system instances. Passing null would leave the manager without a helper and break all later CreateFileSystem calls, so the null argument is rejected immediately.

Solutions

1. Instantiate a concrete IFileSystemHelper (e.g. DefaultFileSystemHelper) and pass it to SetFileSystemHelper.
2. Check why the helper reference is null — fix construction or initialization order.
3. Register the helper during framework initialization before any file system usage.

Example fix

// before
fileSystemManager.SetFileSystemHelper(null); // or uninitialized field
// after
fileSystemManager.SetFileSystemHelper(new DefaultFileSystemHelper());

if (fileSystemHelper == null)
    throw new InvalidOperationException("File system helper must be constructed before registration.");
fileSystemManager.SetFileSystemHelper(fileSystemHelper);

static bool IsValidHelper(IFileSystemHelper helper) => helper != null;

try { fileSystemManager.SetFileSystemHelper(helper); }
catch (GameFrameworkException ex) when (ex.Message == "File system helper is invalid.") { /* helper construction failed — fail fast during bootstrap */ }

When it happens

Trigger: Calling FileSystemManager.SetFileSystemHelper(null), typically when the helper dependency failed to construct or was not yet instantiated.

Common situations: Initialization order bugs where a helper field is still null at setup time; a factory returning null; refactoring that removed the helper creation.

Related errors

• Create file system ' ' failure.
• Data provider helper is invalid.
• Data provider helper is invalid.
• Data table helper is invalid.
• Download manager is invalid.

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

Appendix: source

Thrown at GameFramework/FileSystem/FileSystemManager.cs:87

            while (m_FileSystems.Count > 0)
            {
                foreach (KeyValuePair<string, FileSystem> fileSystem in m_FileSystems)
                {
                    DestroyFileSystem(fileSystem.Value, false);
                    break;
                }
            }
        }

        /// <summary>
        /// 设置文件系统辅助器。
        /// </summary>
        /// <param name="fileSystemHelper">文件系统辅助器。</param>
        public void SetFileSystemHelper(IFileSystemHelper fileSystemHelper)
        {
            if (fileSystemHelper == null)
            {
                throw new GameFrameworkException("File system helper is invalid.");
            }

            m_FileSystemHelper = fileSystemHelper;
        }

        /// <summary>
        /// 检查是否存在文件系统。
        /// </summary>
        /// <param name="fullPath">要检查的文件系统的完整路径。</param>
        /// <returns>是否存在文件系统。</returns>
        public bool HasFileSystem(string fullPath)
        {
            if (string.IsNullOrEmpty(fullPath))
            {
                throw new GameFrameworkException("Full path is invalid.");
            }

            return m_FileSystems.ContainsKey(Utility.Path.GetRegularPath(fullPath));

View on GitHub (pinned to d0c010b051)