{"record":{"id":"b580212027b8860c","repo":"EllanJiang/GameFramework","slug":"internal-download-error","errorCode":null,"errorMessage":"Internal download error.","messagePattern":"Internal download error\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Download/DownloadManager.DownloadAgent.cs","lineNumber":326,"sourceCode":"            }\n\n            private void OnDownloadAgentHelperUpdateLength(object sender, DownloadAgentHelperUpdateLengthEventArgs e)\n            {\n                m_WaitTime = 0f;\n                m_DownloadedLength += e.DeltaLength;\n                if (DownloadAgentUpdate != null)\n                {\n                    DownloadAgentUpdate(this, e.DeltaLength);\n                }\n            }\n\n            private void OnDownloadAgentHelperComplete(object sender, DownloadAgentHelperCompleteEventArgs e)\n            {\n                m_WaitTime = 0f;\n                m_DownloadedLength = e.Length;\n                if (m_SavedLength != CurrentLength)\n                {\n                    throw new GameFrameworkException(\"Internal download error.\");\n                }\n\n                m_Helper.Reset();\n                m_FileStream.Close();\n                m_FileStream = null;\n\n                if (File.Exists(m_Task.DownloadPath))\n                {\n                    File.Delete(m_Task.DownloadPath);\n                }\n\n                File.Move(Utility.Text.Format(\"{0}.download\", m_Task.DownloadPath), m_Task.DownloadPath);\n\n                m_Task.Status = DownloadTaskStatus.Done;\n\n                if (DownloadAgentSuccess != null)\n                {\n                    DownloadAgentSuccess(this, e.Length);","sourceCodeStart":308,"sourceCodeEnd":344,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Download/DownloadManager.DownloadAgent.cs#L308-L344","documentation":"OnDownloadAgentHelperComplete fires when the download helper reports completion. The agent maintains counters (m_SavedLength via flushed bytes, CurrentLength via total reported); this error means these internal counters disagreed at completion, i.e. the library's own state machine was violated rather than a caller mistake.","triggerScenarios":"DownloadAgentHelperComplete event arrives while m_SavedLength != CurrentLength — e.g. helper reported total bytes inconsistent with what was written to the file stream, or Complete fired before all UpdateBytes/UpdateLength events were processed.","commonSituations":"Custom IDownloadAgentHelper implementations that raise Complete with a Length differing from the sum of reported byte updates, skipping update events on some platforms, or race conditions in async helpers.","solutions":["Fix the custom IDownloadAgentHelper so its Complete event Length equals the total bytes reported through UpdateBytes/UpdateLength","Ensure all byte/length update events are delivered before Complete (no dropped or reordered callbacks)","Log m_SavedLength and CurrentLength to identify which counter drifts and under what network conditions"],"exampleFix":"// before\nonComplete(totalReceived);\n// after\nif (totalReceived == reportedBytesSum) onComplete(totalReceived); else onError(...);","handlingStrategy":"try-catch","validationCode":"long reportedSum = /* sum of UpdateBytes/UpdateLength reported bytes */; if (reportedSum != expectedTotal) helperCallbackOnError();","typeGuard":null,"tryCatchPattern":"try { agent.Process(...); } catch (GameFrameworkException ex) when (ex.Message == \"Internal download error.\") { Log.Error(\"Download agent state inconsistent (saved != current length); check custom helper event ordering\"); RestartDownload(); }","preventionTips":["Keep Complete event's Length equal to the sum of all reported byte updates","Never drop or reorder UpdateBytes/UpdateLength events in custom helpers","Add debug counters around your helper's callbacks to catch drift"],"tags":["download","internal-state","custom-helper","unity","gameframework"],"backgroundTag":"internal-invariant-violation","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"}