{"record":{"id":"6b6a80912464b008","repo":"EllanJiang/GameFramework","slug":"create-file-system-stream-for-0-failure","errorCode":null,"errorMessage":"Create file system stream for '{0}' failure.","messagePattern":"Create file system stream for '(.+?)' failure\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/FileSystem/FileSystemManager.cs","lineNumber":168,"sourceCode":"            {\n                throw new GameFrameworkException(\"Access is invalid.\");\n            }\n\n            if (access == FileSystemAccess.Read)\n            {\n                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>","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/FileSystem/FileSystemManager.cs#L150-L186","documentation":"FileSystemManager.CreateFileSystem throws this when the registered IFileSystemHelper.CreateFileSystemStream returns null for the given path, access mode, and create=true. The helper is user-provided (e.g. DefaultFileSystemHelper); a null return means it could not open a stream for creating the file system file, so the manager aborts.","triggerScenarios":"Calling CreateFileSystem when the bound FileSystemHelper's CreateFileSystemStream(fullPath, access, true) returns null - typically because the helper type is not registered (SetFileSystemHelper never called or called with a null/default instance) or the stream creation failed for the given access mode.","commonSituations":"Forgetting FileSystemComponent.SetFileSystemHelper / SetFileSystemHelperType before initialization; a custom IFileSystemHelper whose CreateFileSystemStream returns null on unsupported platforms or for invalid access values; file paths the helper cannot open.","solutions":["Register a file system helper before use: SetFileSystemHelper(new DefaultFileSystemHelper()) or SetFileSystemHelperType<DefaultFileSystemHelper>() on the FileSystemComponent.","Inspect the custom IFileSystemHelper.CreateFileSystemStream implementation and make it return a valid FileSystemStream or throw a descriptive exception instead of returning null.","Verify fullPath and FileSystemAccess arguments passed to CreateFileSystem are valid for the helper."],"exampleFix":"// before\nfileSystemManager.CreateFileSystem(fullPath, FileSystemAccess.ReadWrite, 1024, 256); // helper never set\n// after\nfileSystemManager.SetFileSystemHelper(new DefaultFileSystemHelper());\nfileSystemManager.CreateFileSystem(fullPath, FileSystemAccess.ReadWrite, 1024, 256);","handlingStrategy":"validation","validationCode":"// Ensure a helper is registered before any Create/Load call\nif (!fileSystemHelperSet)\n    fileSystemManager.SetFileSystemHelper(new DefaultFileSystemHelper());","typeGuard":null,"tryCatchPattern":"try { fs = manager.CreateFileSystem(path, access, mc, mb); }\ncatch (GameFrameworkException ex) when (ex.Message.Contains(\"Create file system stream\")) { Log.Error(\"FileSystemHelper missing or failed for \" + path); }","preventionTips":["Call SetFileSystemHelper/SetFileSystemHelperType during framework initialization.","Custom helpers must never return null - throw descriptive exceptions instead.","Test file system creation on every target platform."],"tags":["filesystem","missing-dependency","gameframework"],"backgroundTag":"missing-dependency","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"}