EllanJiang/GameFramework · error · GameFrameworkException

Max file count can not larger than max block count.

Error message

Max file count can not larger than max block count.

What it means

Each file entry consumes at least one block, so the filesystem cannot support more files than blocks. FileSystem.Create enforces maxFileCount <= maxBlockCount and throws when this invariant is violated.

Solutions

  1. Set maxBlockCount >= maxFileCount when calling Create
  2. Add a cross-field validation to your settings loader that clamps or rejects file count > block count
  3. If fewer blocks are desired, reduce maxFileCount proportionally — one block per file is the minimum
  4. Re-check parameter order in the Create call

Example fix

// before
var fs = FileSystem.Create(path, access, stream, maxFileCount: 100, maxBlockCount: 50);
// after
int maxBlockCount = Math.Max(50, 100); // blocks >= files
var fs = FileSystem.Create(path, access, stream, 100, maxBlockCount);
Defensive patterns

Strategy: validation

Validate before calling

if (maxFileCount > maxBlockCount) throw new ArgumentException("maxBlockCount must be >= maxFileCount");
FileSystem.Create(fullPath, access, stream, maxFileCount, maxBlockCount);

Type guard

bool AreValidCapacities(int files, int blocks) => files > 0 && blocks > 0 && blocks >= files;

Try / catch

try { var fs = FileSystem.Create(path, access, stream, fc, bc); }
catch (GameFrameworkException ex) when (ex.Message.Contains("can not larger than max block count")) { Log.Error($"files={fc} blocks={bc}: each file needs at least one block"); }

Prevention

When it happens

Trigger: Calling FileSystem.Create with maxFileCount > maxBlockCount — e.g. Create(path, access, stream, 100, 50).

Common situations: Independent config values for files and blocks tuned separately without a cross-check; users lowering block count to save space without realizing each file needs a block; reordered arguments putting the block count in the file count slot.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at GameFramework/FileSystem/FileSystem.cs:153

        /// <param name="stream">要创建的文件系统的文件系统流。</param>
        /// <param name="maxFileCount">要创建的文件系统的最大文件数量。</param>
        /// <param name="maxBlockCount">要创建的文件系统的最大块数据数量。</param>
        /// <returns>创建的文件系统。</returns>
        public static FileSystem Create(string fullPath, FileSystemAccess access, FileSystemStream stream, int maxFileCount, int maxBlockCount)
        {
            if (maxFileCount <= 0)
            {
                throw new GameFrameworkException("Max file count is invalid.");
            }

            if (maxBlockCount <= 0)
            {
                throw new GameFrameworkException("Max block count is invalid.");
            }

            if (maxFileCount > maxBlockCount)
            {
                throw new GameFrameworkException("Max file count can not larger than max block count.");
            }

            FileSystem fileSystem = new FileSystem(fullPath, access, stream);
            fileSystem.m_HeaderData = new HeaderData(maxFileCount, maxBlockCount);
            CalcOffsets(fileSystem);
            Utility.Marshal.StructureToBytes(fileSystem.m_HeaderData, HeaderDataSize, s_CachedBytes);

            try
            {
                stream.Write(s_CachedBytes, 0, HeaderDataSize);
                stream.SetLength(fileSystem.m_FileDataOffset);
                return fileSystem;
            }
            catch
            {
                fileSystem.Shutdown();
                return null;
            }

View on GitHub (pinned to d0c010b051)