EllanJiang/GameFramework · error · GameFrameworkException

Index is invalid.

Error message

Index is invalid.

What it means

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.

Solutions

1. Clamp or validate offset >= 0 before calling.
2. Fix the cursor arithmetic that produced the negative offset.
3. Note the library clamps offset > file length but not negatives, so pre-validate.

Example fix

// before
int offset = position - chunkSize; // can go negative
fs.ReadFileSegment(name, offset, len);

// after
int offset = Math.Max(0, position - chunkSize);
fs.ReadFileSegment(name, offset, len);

if (offset < 0)
    throw new ArgumentOutOfRangeException(nameof(offset), offset, "Offset must be >= 0");
byte[] seg = fs.ReadFileSegment(name, offset, length);

static bool IsValidRange(int offset, int length) => offset >= 0 && length >= 0;

try
{
    byte[] seg = fs.ReadFileSegment(name, offset, length);
}
catch (GameFrameworkException ex) when (ex.Message == "Index is invalid.")
{
    // clamp offset and retry
}

When it happens

Trigger: Calling ReadFileSegment(name, -1, len) or any overload forwarding a negative offset (e.g. ReadFileSegment(name, offset, buffer)).

Common situations: Computed offsets from partial-read state that went negative (e.g. offset -= chunkSize without clamping); int underflow; off-by-one cursor math.

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

• Length is invalid.
• File path is invalid
• Length is invalid.
• Max block count is invalid.
• Max file count is invalid.

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

Appendix: source

Thrown at GameFramework/FileSystem/FileSystem.cs:520

        /// <param name="name">要读取片段的文件名称。</param>
        /// <param name="offset">要读取片段的偏移。</param>
        /// <param name="length">要读取片段的长度。</param>
        /// <returns>存储读取文件片段内容的二进制流。</returns>
        public byte[] ReadFileSegment(string name, int offset, int length)
        {
            if (m_Access != FileSystemAccess.Read && m_Access != FileSystemAccess.ReadWrite)
            {
                throw new GameFrameworkException("File system is not readable.");
            }

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

            if (offset < 0)
            {
                throw new GameFrameworkException("Index is invalid.");
            }

            if (length < 0)
            {
                throw new GameFrameworkException("Length is invalid.");
            }

            FileInfo fileInfo = GetFileInfo(name);
            if (!fileInfo.IsValid)
            {
                return null;
            }

            if (offset > fileInfo.Length)
            {
                offset = fileInfo.Length;
            }

View on GitHub (pinned to d0c010b051)