{"record":{"id":"3e5261124d10e9f7","repo":"EllanJiang/GameFramework","slug":"index-is-invalid","errorCode":null,"errorMessage":"Index is invalid.","messagePattern":"Index is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/FileSystem/FileSystem.cs","lineNumber":520,"sourceCode":"        /// <param name=\"name\">要读取片段的文件名称。</param>\n        /// <param name=\"offset\">要读取片段的偏移。</param>\n        /// <param name=\"length\">要读取片段的长度。</param>\n        /// <returns>存储读取文件片段内容的二进制流。</returns>\n        public byte[] ReadFileSegment(string name, int offset, int length)\n        {\n            if (m_Access != FileSystemAccess.Read && m_Access != FileSystemAccess.ReadWrite)\n            {\n                throw new GameFrameworkException(\"File system is not readable.\");\n            }\n\n            if (string.IsNullOrEmpty(name))\n            {\n                throw new GameFrameworkException(\"Name is invalid.\");\n            }\n\n            if (offset < 0)\n            {\n                throw new GameFrameworkException(\"Index is invalid.\");\n            }\n\n            if (length < 0)\n            {\n                throw new GameFrameworkException(\"Length is invalid.\");\n            }\n\n            FileInfo fileInfo = GetFileInfo(name);\n            if (!fileInfo.IsValid)\n            {\n                return null;\n            }\n\n            if (offset > fileInfo.Length)\n            {\n                offset = fileInfo.Length;\n            }\n","sourceCodeStart":502,"sourceCodeEnd":538,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/FileSystem/FileSystem.cs#L502-L538","documentation":"FileSystem.ReadFileSegment(name, offset, length) throws this when offset is negative. Offsets index into the stored file data, and negative values are meaningless, so they are rejected before resolving the file entry.","triggerScenarios":"Calling ReadFileSegment(name, -1, len) or any overload forwarding a negative offset (e.g. ReadFileSegment(name, offset, buffer)).","commonSituations":"Computed offsets from partial-read state that went negative (e.g. offset -= chunkSize without clamping); int underflow; off-by-one cursor math.","solutions":["Clamp or validate offset >= 0 before calling.","Fix the cursor arithmetic that produced the negative offset.","Note the library clamps offset > file length but not negatives, so pre-validate."],"exampleFix":"// before\nint offset = position - chunkSize; // can go negative\nfs.ReadFileSegment(name, offset, len);\n\n// after\nint offset = Math.Max(0, position - chunkSize);\nfs.ReadFileSegment(name, offset, len);","handlingStrategy":"validation","validationCode":"if (offset < 0)\n    throw new ArgumentOutOfRangeException(nameof(offset), offset, \"Offset must be >= 0\");\nbyte[] seg = fs.ReadFileSegment(name, offset, length);","typeGuard":"static bool IsValidRange(int offset, int length) => offset >= 0 && length >= 0;","tryCatchPattern":"try\n{\n    byte[] seg = fs.ReadFileSegment(name, offset, length);\n}\ncatch (GameFrameworkException ex) when (ex.Message == \"Index is invalid.\")\n{\n    // clamp offset and retry\n}","preventionTips":["Clamp cursors with Math.Max(0, ...) after every adjustment.","Remember the library clamps large offsets but throws on negative ones."],"tags":["filesystem","argument-validation","range","gameframework"],"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-23T08:17:48.524Z"}