EllanJiang/GameFramework · error · GameFrameworkException

Offset is invalid.

Error message

Offset is invalid.

What it means

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.

Solutions

1. Ensure the offset passed to FileInfo is a non-negative byte position within the filesystem stream before constructing it
2. Check the code that computes the offset (e.g. accumulated block positions) for underflow or sentinel values like -1
3. If offsets come from a loaded archive, validate or re-export the filesystem file; it may be corrupted
4. Wrap FileInfo construction in try-catch to surface which name/offset pair failed

Example fix

// before
var info = new FileInfo(name, -1L, length); // sentinel offset
// after
long offset = 0L; // real byte offset of the entry in the stream
if (offset < 0L) throw new InvalidOperationException("offset must be >= 0");
var info = new FileInfo(name, offset, length);

if (offset < 0L) throw new ArgumentOutOfRangeException(nameof(offset), offset, "offset must be >= 0");
var info = new FileInfo(name, offset, length);

bool IsValidOffset(long offset) => offset >= 0L;

try { var info = new FileInfo(name, offset, length); }
catch (GameFrameworkException ex) when (ex.Message == "Offset is invalid.") { Log.Error($"Bad offset {offset} for '{name}'"); }

When it happens

Trigger: 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.

Common situations: 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'.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Length is invalid.
• Max file count is invalid.
• Max block count is invalid.
• Name is invalid.
• Stream is not writable.

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

Appendix: source

Thrown at GameFramework/FileSystem/FileInfo.cs:37

        private readonly long m_Offset;
        private readonly int m_Length;

        /// <summary>
        /// 初始化文件信息的新实例。
        /// </summary>
        /// <param name="name">文件名称。</param>
        /// <param name="offset">文件偏移。</param>
        /// <param name="length">文件长度。</param>
        public FileInfo(string name, long offset, int length)
        {
            if (string.IsNullOrEmpty(name))
            {
                throw new GameFrameworkException("Name is invalid.");
            }

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

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

            m_Name = name;
            m_Offset = offset;
            m_Length = length;
        }

        /// <summary>
        /// 获取文件信息是否有效。
        /// </summary>
        public bool IsValid
        {
            get

View on GitHub (pinned to d0c010b051)