{"record":{"id":"9405aef082b3dca9","repo":"EllanJiang/GameFramework","slug":"length-is-invalid","errorCode":null,"errorMessage":"Length is invalid.","messagePattern":"Length is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Download/DownloadAgentHelperCompleteEventArgs.cs","lineNumber":41,"sourceCode":"        /// <summary>\n        /// 获取下载的数据大小。\n        /// </summary>\n        public long Length\n        {\n            get;\n            private set;\n        }\n\n        /// <summary>\n        /// 创建下载代理辅助器完成事件。\n        /// </summary>\n        /// <param name=\"length\">下载的数据大小。</param>\n        /// <returns>创建的下载代理辅助器完成事件。</returns>\n        public static DownloadAgentHelperCompleteEventArgs Create(long length)\n        {\n            if (length < 0L)\n            {\n                throw new GameFrameworkException(\"Length is invalid.\");\n            }\n\n            DownloadAgentHelperCompleteEventArgs downloadAgentHelperCompleteEventArgs = ReferencePool.Acquire<DownloadAgentHelperCompleteEventArgs>();\n            downloadAgentHelperCompleteEventArgs.Length = length;\n            return downloadAgentHelperCompleteEventArgs;\n        }\n\n        /// <summary>\n        /// 清理下载代理辅助器完成事件。\n        /// </summary>\n        public override void Clear()\n        {\n            Length = 0L;\n        }\n    }\n}\n","sourceCodeStart":23,"sourceCodeEnd":58,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Download/DownloadAgentHelperCompleteEventArgs.cs#L23-L58","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the download agent helper so it reports the true non-negative byte count (or signals failure through the error callback instead).","Clamp or validate the length in the helper before raising the completion callback: use Math.Max(0, length) only if 0 is meaningful.","Return failure via the helper's error event for negative/unknown sizes rather than the complete event."],"exampleFix":"// before (custom IDownloadAgentHelper)\nonComplete(this, DownloadAgentHelperCompleteEventArgs.Create(bytesRead)); // bytesRead may be -1\n// after\nif (bytesRead >= 0)\n    onComplete(this, DownloadAgentHelperCompleteEventArgs.Create(bytesRead));\nelse\n    onError(this, DownloadAgentHelperErrorEventArgs.Create(DownloadErrorCode.Unknown, \"negative length\"));","handlingStrategy":"validation","validationCode":"if (length < 0) raiseDownloadError(); // do not fire the complete event","typeGuard":"static bool IsValidDownloadLength(long len) => len >= 0L;","tryCatchPattern":"try { var e = DownloadAgentHelperCompleteEventArgs.Create(length); }\ncatch (GameFrameworkException) { Log.Error(\"Download helper reported a negative length\"); }","preventionTips":["Report download failures via the error event, not the complete event with a sentinel -1","Validate sizes parsed from headers (Content-Length) before use","Use unsigned-checked arithmetic for byte counts"],"tags":["download","eventargs","validation","csharp"],"backgroundTag":"argument-out-of-range","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"}