{"record":{"id":"2d9dc3fd5b18f958","repo":"EllanJiang/GameFramework","slug":"load-file-system-0-failure","errorCode":null,"errorMessage":"Load file system '{0}' failure.","messagePattern":"Load file system '(.+?)' failure\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/FileSystem/FileSystemManager.cs","lineNumber":220,"sourceCode":"            }\n\n            fullPath = Utility.Path.GetRegularPath(fullPath);\n            if (m_FileSystems.ContainsKey(fullPath))\n            {\n                throw new GameFrameworkException(Utility.Text.Format(\"File system '{0}' is already exist.\", fullPath));\n            }\n\n            FileSystemStream fileSystemStream = m_FileSystemHelper.CreateFileSystemStream(fullPath, access, false);\n            if (fileSystemStream == null)\n            {\n                throw new GameFrameworkException(Utility.Text.Format(\"Create file system stream for '{0}' failure.\", fullPath));\n            }\n\n            FileSystem fileSystem = FileSystem.Load(fullPath, access, fileSystemStream);\n            if (fileSystem == null)\n            {\n                fileSystemStream.Close();\n                throw new GameFrameworkException(Utility.Text.Format(\"Load file system '{0}' failure.\", fullPath));\n            }\n\n            m_FileSystems.Add(fullPath, fileSystem);\n            return fileSystem;\n        }\n\n        /// <summary>\n        /// 销毁文件系统。\n        /// </summary>\n        /// <param name=\"fileSystem\">要销毁的文件系统。</param>\n        /// <param name=\"deletePhysicalFile\">是否删除文件系统对应的物理文件。</param>\n        public void DestroyFileSystem(IFileSystem fileSystem, bool deletePhysicalFile)\n        {\n            if (fileSystem == null)\n            {\n                throw new GameFrameworkException(\"File system is invalid.\");\n            }\n","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/FileSystem/FileSystemManager.cs#L202-L238","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check HasFileSystem/File.Exists first and fall back to CreateFileSystem when the file system does not exist yet.","Delete the corrupt file and recreate it via CreateFileSystem, re-generating its content.","Verify the file was produced by the same GameFramework FileSystem format/version."],"exampleFix":"// before\nvar fs = fileSystemManager.LoadFileSystem(fullPath, FileSystemAccess.ReadWrite); // crashes on first run\n// after\nvar fs = fileSystemManager.HasFileSystem(fullPath)\n    ? fileSystemManager.LoadFileSystem(fullPath, FileSystemAccess.ReadWrite)\n    : fileSystemManager.CreateFileSystem(fullPath, FileSystemAccess.ReadWrite, 1024, 256);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { fs = manager.LoadFileSystem(path, access); }\ncatch (GameFrameworkException ex) when (ex.Message.Contains(\"Load file system\")) {\n    // file missing, empty, or corrupt: recreate\n    System.IO.File.Delete(path);\n    fs = manager.CreateFileSystem(path, FileSystemAccess.ReadWrite, maxFileCount, maxBlockCount);\n}","preventionTips":["On first launch, always CreateFileSystem instead of LoadFileSystem.","Validate file size > 0 before loading.","Keep backup/recreate logic for files damaged by interrupted writes."],"tags":["filesystem","corrupt-data","gameframework"],"backgroundTag":"file-read-failed","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}