EllanJiang/GameFramework · error · GameFrameworkException

Load file system ' ' failure.

Error message

Load file system '{0}' failure.

What it means

FileSystemManager.LoadFileSystem throws this when FileSystem.Load(fullPath, access, fileSystemStream) returns null - the stream opened fine but the file system could not be loaded from it. The manager closes the stream before throwing. This usually means the file does not contain a valid file system (wrong/empty/corrupt file at the path).

Solutions

1. Check HasFileSystem/File.Exists first and fall back to CreateFileSystem when the file system does not exist yet.
2. Delete the corrupt file and recreate it via CreateFileSystem, re-generating its content.
3. Verify the file was produced by the same GameFramework FileSystem format/version.

Example fix

// before
var fs = fileSystemManager.LoadFileSystem(fullPath, FileSystemAccess.ReadWrite); // crashes on first run
// after
var fs = fileSystemManager.HasFileSystem(fullPath)
    ? fileSystemManager.LoadFileSystem(fullPath, FileSystemAccess.ReadWrite)
    : fileSystemManager.CreateFileSystem(fullPath, FileSystemAccess.ReadWrite, 1024, 256);

try { fs = manager.LoadFileSystem(path, access); }
catch (GameFrameworkException ex) when (ex.Message.Contains("Load file system")) {
    // file missing, empty, or corrupt: recreate
    System.IO.File.Delete(path);
    fs = manager.CreateFileSystem(path, FileSystemAccess.ReadWrite, maxFileCount, maxBlockCount);
}

When it happens

Trigger: Calling LoadFileSystem on a path whose physical file is empty, was never created by CreateFileSystem, was written by an incompatible GameFramework version, or is corrupt.

Common situations: Assuming a file system exists and calling Load on first app launch when nothing was created yet; version upgrades changing the on-disk format; truncated files from interrupted writes.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Offset is invalid.
• Length is invalid.
• String ' ' is too long.
• Full path is invalid.
• Access is invalid.

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

Appendix: source

Thrown at GameFramework/FileSystem/FileSystemManager.cs:220

            }

            fullPath = Utility.Path.GetRegularPath(fullPath);
            if (m_FileSystems.ContainsKey(fullPath))
            {
                throw new GameFrameworkException(Utility.Text.Format("File system '{0}' is already exist.", fullPath));
            }

            FileSystemStream fileSystemStream = m_FileSystemHelper.CreateFileSystemStream(fullPath, access, false);
            if (fileSystemStream == null)
            {
                throw new GameFrameworkException(Utility.Text.Format("Create file system stream for '{0}' failure.", fullPath));
            }

            FileSystem fileSystem = FileSystem.Load(fullPath, access, fileSystemStream);
            if (fileSystem == null)
            {
                fileSystemStream.Close();
                throw new GameFrameworkException(Utility.Text.Format("Load file system '{0}' failure.", fullPath));
            }

            m_FileSystems.Add(fullPath, fileSystem);
            return fileSystem;
        }

        /// <summary>
        /// 销毁文件系统。
        /// </summary>
        /// <param name="fileSystem">要销毁的文件系统。</param>
        /// <param name="deletePhysicalFile">是否删除文件系统对应的物理文件。</param>
        public void DestroyFileSystem(IFileSystem fileSystem, bool deletePhysicalFile)
        {
            if (fileSystem == null)
            {
                throw new GameFrameworkException("File system is invalid.");
            }

View on GitHub (pinned to d0c010b051)