{"record":{"id":"8bd6c823c180ad22","repo":"EllanJiang/GameFramework","slug":"max-block-count-is-invalid","errorCode":null,"errorMessage":"Max block count is invalid.","messagePattern":"Max block count is invalid\\.","errorType":"validation","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/FileSystem/FileSystem.cs","lineNumber":148,"sourceCode":"        /// <summary>\n        /// 创建文件系统。\n        /// </summary>\n        /// <param name=\"fullPath\">要创建的文件系统的完整路径。</param>\n        /// <param name=\"access\">要创建的文件系统的访问方式。</param>\n        /// <param name=\"stream\">要创建的文件系统的文件系统流。</param>\n        /// <param name=\"maxFileCount\">要创建的文件系统的最大文件数量。</param>\n        /// <param name=\"maxBlockCount\">要创建的文件系统的最大块数据数量。</param>\n        /// <returns>创建的文件系统。</returns>\n        public static FileSystem Create(string fullPath, FileSystemAccess access, FileSystemStream stream, int maxFileCount, int maxBlockCount)\n        {\n            if (maxFileCount <= 0)\n            {\n                throw new GameFrameworkException(\"Max file count is invalid.\");\n            }\n\n            if (maxBlockCount <= 0)\n            {\n                throw new GameFrameworkException(\"Max block count is invalid.\");\n            }\n\n            if (maxFileCount > maxBlockCount)\n            {\n                throw new GameFrameworkException(\"Max file count can not larger than max block count.\");\n            }\n\n            FileSystem fileSystem = new FileSystem(fullPath, access, stream);\n            fileSystem.m_HeaderData = new HeaderData(maxFileCount, maxBlockCount);\n            CalcOffsets(fileSystem);\n            Utility.Marshal.StructureToBytes(fileSystem.m_HeaderData, HeaderDataSize, s_CachedBytes);\n\n            try\n            {\n                stream.Write(s_CachedBytes, 0, HeaderDataSize);\n                stream.SetLength(fileSystem.m_FileDataOffset);\n                return fileSystem;\n            }","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/FileSystem/FileSystem.cs#L130-L166","documentation":"FileSystem.Create requires maxBlockCount to be positive because the filesystem stores data in fixed-size blocks and the header must reserve at least one. Non-positive values make the archive layout invalid, so Create throws.","triggerScenarios":"Calling FileSystem.Create with maxBlockCount <= 0, commonly from a missing or zero-defaulting config value, or a mis-ordered argument list.","commonSituations":"Settings object where MaxBlocks was never set; computed block count from a formula that returned zero for empty input; swapping maxFileCount and maxBlockCount arguments by mistake.","solutions":["Pass a positive maxBlockCount (must also be >= maxFileCount)","Validate any config-derived value before calling Create","Check parameter order in the Create call — maxFileCount comes before maxBlockCount","Size blocks based on expected data volume, leaving growth headroom"],"exampleFix":"// before\nvar fs = FileSystem.Create(path, access, stream, files, 0);\n// after\nint maxBlockCount = Math.Max(files, 64);\nvar fs = FileSystem.Create(path, access, stream, files, maxBlockCount);","handlingStrategy":"validation","validationCode":"if (maxBlockCount <= 0) throw new ArgumentOutOfRangeException(nameof(maxBlockCount), maxBlockCount, \"must be positive\");\nFileSystem.Create(fullPath, access, stream, maxFileCount, maxBlockCount);","typeGuard":"bool IsValidMaxBlockCount(int n) => n > 0;","tryCatchPattern":"try { var fs = FileSystem.Create(path, access, stream, fc, bc); }\ncatch (GameFrameworkException ex) when (ex.Message == \"Max block count is invalid.\") { Log.Error($\"maxBlockCount={bc} — check config source\"); }","preventionTips":["Validate config-driven capacity values at load time","Ensure the block count is derived from actual data-size needs, not left at a zero default","Keep parameter order (maxFileCount, maxBlockCount) straight"],"tags":["gameframework","filesystem","argument-validation"],"backgroundTag":"invalid-config-value","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}