{"record":{"id":"c0b8b66e309d8649","repo":"EllanJiang/GameFramework","slug":"name-0-is-too-long","errorCode":null,"errorMessage":"Name '{0}' is too long.","messagePattern":"Name '(.+?)' is too long\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/FileSystem/FileSystem.cs","lineNumber":821,"sourceCode":"        /// <param name=\"buffer\">存储写入文件内容的二进制流。</param>\n        /// <param name=\"startIndex\">存储写入文件内容的二进制流的起始位置。</param>\n        /// <param name=\"length\">存储写入文件内容的二进制流的长度。</param>\n        /// <returns>是否写入指定文件成功。</returns>\n        public bool WriteFile(string name, byte[] buffer, int startIndex, int length)\n        {\n            if (m_Access != FileSystemAccess.Write && m_Access != FileSystemAccess.ReadWrite)\n            {\n                throw new GameFrameworkException(\"File system is not writable.\");\n            }\n\n            if (string.IsNullOrEmpty(name))\n            {\n                throw new GameFrameworkException(\"Name is invalid.\");\n            }\n\n            if (name.Length > byte.MaxValue)\n            {\n                throw new GameFrameworkException(Utility.Text.Format(\"Name '{0}' is too long.\", name));\n            }\n\n            if (buffer == null)\n            {\n                throw new GameFrameworkException(\"Buffer is invalid.\");\n            }\n\n            if (startIndex < 0 || length < 0 || startIndex + length > buffer.Length)\n            {\n                throw new GameFrameworkException(\"Start index or length is invalid.\");\n            }\n\n            bool hasFile = false;\n            int oldBlockIndex = -1;\n            if (m_FileDatas.TryGetValue(name, out oldBlockIndex))\n            {\n                hasFile = true;\n            }","sourceCodeStart":803,"sourceCodeEnd":839,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/FileSystem/FileSystem.cs#L803-L839","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Shorten the name before writing — store only the file name, not the full path, and keep it under 255 characters.","Check name.Length > byte.MaxValue in caller code and either truncate deterministically or hash the long identifier into a fixed-length key.","If long identifiers are unavoidable, keep a mapping (long id -> short stored key) in a separate metadata file."],"exampleFix":"// before\nfs.WriteFile(fullPath, buffer); // full path, may exceed 255 chars\n// after\nvar name = Path.GetFileName(fullPath);\nif (name.Length > byte.MaxValue) name = Utility.Hash X.GetSha256String(fullPath); // fixed-length key\nfs.WriteFile(name, buffer);","handlingStrategy":"validation","validationCode":"if (name != null && name.Length > byte.MaxValue) throw new ArgumentException($\"Name exceeds {byte.MaxValue} chars: {name}\", nameof(name));","typeGuard":"static bool IsStorableName(string name) => !string.IsNullOrEmpty(name) && name.Length <= byte.MaxValue;","tryCatchPattern":"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 */ }","preventionTips":["Store file names, not full paths, in the file system.","Hash or truncate identifiers that can exceed 255 characters.","Enforce the 255-char limit in the name-generation helper."],"tags":["gameframework","filesystem","name-too-long","write","limit"],"backgroundTag":"value-out-of-range","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"}