EllanJiang/GameFramework · error · GameFrameworkException

Length is invalid.

Error message

Length is invalid.

What it means

DownloadAgentHelperCompleteEventArgs.Create(length) throws this when length is negative. A download completion event carries the total byte count of the downloaded data, which can never be negative; a negative value means the download helper reported corrupted size information. The guard protects the event args pooled via ReferencePool.

Solutions

1. Fix the download agent helper so it reports the true non-negative byte count (or signals failure through the error callback instead).
2. Clamp or validate the length in the helper before raising the completion callback: use Math.Max(0, length) only if 0 is meaningful.
3. Return failure via the helper's error event for negative/unknown sizes rather than the complete event.

Example fix

// before (custom IDownloadAgentHelper)
onComplete(this, DownloadAgentHelperCompleteEventArgs.Create(bytesRead)); // bytesRead may be -1
// after
if (bytesRead >= 0)
    onComplete(this, DownloadAgentHelperCompleteEventArgs.Create(bytesRead));
else
    onError(this, DownloadAgentHelperErrorEventArgs.Create(DownloadErrorCode.Unknown, "negative length"));

if (length < 0) raiseDownloadError(); // do not fire the complete event

static bool IsValidDownloadLength(long len) => len >= 0L;

try { var e = DownloadAgentHelperCompleteEventArgs.Create(length); }
catch (GameFrameworkException) { Log.Error("Download helper reported a negative length"); }

When it happens

Trigger: A custom IDownloadAgentHelper implementation calling the completion callback with a negative length (e.g. from a failed response stream size or misread Content-Length); arithmetic underflow when computing remaining bytes.

Common situations: Writing a custom download agent helper that propagates -1 as an error code into the completion event; parsing HTTP Content-Length incorrectly; off-by-underflow on long arithmetic.

Related errors

• Bytes is invalid.
• Path is invalid.
• Path is invalid.
• Data string is invalid.
• Data bytes is invalid.

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

Appendix: source

Thrown at GameFramework/Download/DownloadAgentHelperCompleteEventArgs.cs:41

        /// <summary>
        /// 获取下载的数据大小。
        /// </summary>
        public long Length
        {
            get;
            private set;
        }

        /// <summary>
        /// 创建下载代理辅助器完成事件。
        /// </summary>
        /// <param name="length">下载的数据大小。</param>
        /// <returns>创建的下载代理辅助器完成事件。</returns>
        public static DownloadAgentHelperCompleteEventArgs Create(long length)
        {
            if (length < 0L)
            {
                throw new GameFrameworkException("Length is invalid.");
            }

            DownloadAgentHelperCompleteEventArgs downloadAgentHelperCompleteEventArgs = ReferencePool.Acquire<DownloadAgentHelperCompleteEventArgs>();
            downloadAgentHelperCompleteEventArgs.Length = length;
            return downloadAgentHelperCompleteEventArgs;
        }

        /// <summary>
        /// 清理下载代理辅助器完成事件。
        /// </summary>
        public override void Clear()
        {
            Length = 0L;
        }
    }
}

View on GitHub (pinned to d0c010b051)