{"record":{"id":"e53a9a3c506ab769","repo":"EllanJiang/GameFramework","slug":"create-file-system-0-failure","errorCode":null,"errorMessage":"Create file system '{0}' failure.","messagePattern":"Create file system '(.+?)' failure\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/FileSystem/FileSystemManager.cs","lineNumber":174,"sourceCode":"                throw new GameFrameworkException(\"Access read is invalid.\");\n            }\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, true);\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.Create(fullPath, access, fileSystemStream, maxFileCount, maxBlockCount);\n            if (fileSystem == null)\n            {\n                throw new GameFrameworkException(Utility.Text.Format(\"Create 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=\"fullPath\">要加载的文件系统的完整路径。</param>\n        /// <param name=\"access\">要加载的文件系统的访问方式。</param>\n        /// <returns>加载的文件系统。</returns>\n        public IFileSystem LoadFileSystem(string fullPath, FileSystemAccess access)\n        {\n            if (m_FileSystemHelper == null)\n            {\n                throw new GameFrameworkException(\"File system helper is invalid.\");\n            }","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/FileSystem/FileSystemManager.cs#L156-L192","documentation":"FileSystemManager.CreateFileSystem throws this when FileSystem.Create(fullPath, access, fileSystemStream, maxFileCount, maxBlockCount) returns null after a stream was successfully opened. FileSystem.Create only fails (returns null) when the stream helpers inside FileSystem (e.g. the header writer) cannot be created, indicating the file system instance could not be initialized on the newly created stream.","triggerScenarios":"Calling CreateFileSystem where the underlying FileSystem.Create returns null - practically only when the internal FileSystemStreamHelper (operating on the supplied stream) fails to be created, e.g. an exotic custom FileSystemStream that the default header logic cannot handle.","commonSituations":"Custom IFileSystemStream implementations that return null from internal helper creation; corrupted or incompatible stream behavior when initializing a brand-new file system file.","solutions":["Use the built-in DefaultFileSystemHelper / default stream implementations so FileSystem.Create succeeds.","If a custom FileSystemStream is used, verify it supports the read/write/seek operations FileSystem initialization requires.","Check maxFileCount and maxBlockCount arguments are sane positive values accepted by the stream."],"exampleFix":"// before\nfileSystemStream = customHelper.CreateFileSystemStream(fullPath, access, true); // returns a stream FileSystem cannot use\n// after\nfileSystemStream = new DefaultFileSystemHelper().CreateFileSystemStream(fullPath, access, true);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { fs = manager.CreateFileSystem(path, access, mc, mb); }\ncatch (GameFrameworkException ex) when (ex.Message.Contains(\"Create file system '\")) { Log.Error(\"FileSystem.Create returned null; check stream/maxFileCount/maxBlockCount: \" + ex.Message); }","preventionTips":["Prefer built-in stream implementations over custom IFileSystemStream.","Validate maxFileCount/maxBlockCount are positive before calling.","Unit-test file system creation when swapping stream implementations."],"tags":["filesystem","initialization","gameframework"],"backgroundTag":"module-init-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"}