{"record":{"id":"e07836650868d80a","repo":"EllanJiang/GameFramework","slug":"offset-is-invalid-fileinfo","errorCode":null,"errorMessage":"Offset is invalid.","messagePattern":"Offset is invalid\\.","errorType":"validation","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/FileSystem/FileInfo.cs","lineNumber":37,"sourceCode":"        private readonly long m_Offset;\n        private readonly int m_Length;\n\n        /// <summary>\n        /// 初始化文件信息的新实例。\n        /// </summary>\n        /// <param name=\"name\">文件名称。</param>\n        /// <param name=\"offset\">文件偏移。</param>\n        /// <param name=\"length\">文件长度。</param>\n        public FileInfo(string name, long offset, int length)\n        {\n            if (string.IsNullOrEmpty(name))\n            {\n                throw new GameFrameworkException(\"Name is invalid.\");\n            }\n\n            if (offset < 0L)\n            {\n                throw new GameFrameworkException(\"Offset is invalid.\");\n            }\n\n            if (length < 0)\n            {\n                throw new GameFrameworkException(\"Length is invalid.\");\n            }\n\n            m_Name = name;\n            m_Offset = offset;\n            m_Length = length;\n        }\n\n        /// <summary>\n        /// 获取文件信息是否有效。\n        /// </summary>\n        public bool IsValid\n        {\n            get","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/FileSystem/FileInfo.cs#L19-L55","documentation":"FileInfo's constructor validates that the byte offset of the file entry inside the game framework filesystem is non-negative. A negative offset means the entry would point before the start of the underlying stream, which would corrupt reads, so GameFramework throws GameFrameworkException immediately.","triggerScenarios":"Calling new FileInfo(name, offset, length) with a negative offset value, or constructing FileInfo instances from a filesystem header whose stored offset fields were corrupted or incorrectly deserialized.","commonSituations":"Loading a corrupted or truncated game filesystem archive where block offsets in the header are garbage; hand-writing FileInfo entries in tooling with offsets computed from bad arithmetic (e.g. uninitialized long defaulting/misread); porting save-file code that uses -1 as a sentinel for 'no offset'.","solutions":["Ensure the offset passed to FileInfo is a non-negative byte position within the filesystem stream before constructing it","Check the code that computes the offset (e.g. accumulated block positions) for underflow or sentinel values like -1","If offsets come from a loaded archive, validate or re-export the filesystem file; it may be corrupted","Wrap FileInfo construction in try-catch to surface which name/offset pair failed"],"exampleFix":"// before\nvar info = new FileInfo(name, -1L, length); // sentinel offset\n// after\nlong offset = 0L; // real byte offset of the entry in the stream\nif (offset < 0L) throw new InvalidOperationException(\"offset must be >= 0\");\nvar info = new FileInfo(name, offset, length);","handlingStrategy":"validation","validationCode":"if (offset < 0L) throw new ArgumentOutOfRangeException(nameof(offset), offset, \"offset must be >= 0\");\nvar info = new FileInfo(name, offset, length);","typeGuard":"bool IsValidOffset(long offset) => offset >= 0L;","tryCatchPattern":"try { var info = new FileInfo(name, offset, length); }\ncatch (GameFrameworkException ex) when (ex.Message == \"Offset is invalid.\") { Log.Error($\"Bad offset {offset} for '{name}'\"); }","preventionTips":["Never use -1 as a sentinel offset; use nullable long instead","Validate offsets computed from block arithmetic before constructing FileInfo","Verify archive headers after deserialization before building FileInfo instances"],"tags":["gameframework","filesystem","argument-validation"],"backgroundTag":"invalid-argument-value","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"}