EllanJiang/GameFramework · error · GameFrameworkException

Name ' ' is too long.

Error message

Name '{0}' is too long.

What it means

WriteFile throws this formatted GameFrameworkException when the file name exceeds byte.MaxValue (255) characters. The on-disk format stores the name length in a single byte, so names longer than 255 characters cannot be serialized. The exception message includes the offending name.

Solutions

1. Shorten the name before writing — store only the file name, not the full path, and keep it under 255 characters.
2. Check name.Length > byte.MaxValue in caller code and either truncate deterministically or hash the long identifier into a fixed-length key.
3. If long identifiers are unavoidable, keep a mapping (long id -> short stored key) in a separate metadata file.

Example fix

// before
fs.WriteFile(fullPath, buffer); // full path, may exceed 255 chars
// after
var name = Path.GetFileName(fullPath);
if (name.Length > byte.MaxValue) name = Utility.Hash X.GetSha256String(fullPath); // fixed-length key
fs.WriteFile(name, buffer);

if (name != null && name.Length > byte.MaxValue) throw new ArgumentException($"Name exceeds {byte.MaxValue} chars: {name}", nameof(name));

static bool IsStorableName(string name) => !string.IsNullOrEmpty(name) && name.Length <= byte.MaxValue;

try { fs.WriteFile(name, buffer, startIndex, length); } catch (GameFrameworkException ex) when (ex.Message.StartsWith("Name '") && ex.Message.Contains("is too long")) { /* shorten or hash the name */ }

When it happens

Trigger: Calling WriteFile with a name whose string length is > 255 — typically long generated names such as concatenated hashes, full paths used as names, or machine-generated identifiers with prefixes/timestamps.

Common situations: Using a full file path as the name instead of just the file name, concatenating folder prefixes repeatedly, or hash+extension names that grew after a format change.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• File system is not writable.
• Offset is invalid.
• Length is invalid.
• String ' ' is too long.
• Full path is invalid.

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

Appendix: source

Thrown at GameFramework/FileSystem/FileSystem.cs:821

        /// <param name="buffer">存储写入文件内容的二进制流。</param>
        /// <param name="startIndex">存储写入文件内容的二进制流的起始位置。</param>
        /// <param name="length">存储写入文件内容的二进制流的长度。</param>
        /// <returns>是否写入指定文件成功。</returns>
        public bool WriteFile(string name, byte[] buffer, int startIndex, int length)
        {
            if (m_Access != FileSystemAccess.Write && m_Access != FileSystemAccess.ReadWrite)
            {
                throw new GameFrameworkException("File system is not writable.");
            }

            if (string.IsNullOrEmpty(name))
            {
                throw new GameFrameworkException("Name is invalid.");
            }

            if (name.Length > byte.MaxValue)
            {
                throw new GameFrameworkException(Utility.Text.Format("Name '{0}' is too long.", name));
            }

            if (buffer == null)
            {
                throw new GameFrameworkException("Buffer is invalid.");
            }

            if (startIndex < 0 || length < 0 || startIndex + length > buffer.Length)
            {
                throw new GameFrameworkException("Start index or length is invalid.");
            }

            bool hasFile = false;
            int oldBlockIndex = -1;
            if (m_FileDatas.TryGetValue(name, out oldBlockIndex))
            {
                hasFile = true;
            }

View on GitHub (pinned to d0c010b051)