EllanJiang/GameFramework · error · GameFrameworkException

Internal download error.

Error message

Internal download error.

What it means

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.

Solutions

1. Fix the custom IDownloadAgentHelper so its Complete event Length equals the total bytes reported through UpdateBytes/UpdateLength
2. Ensure all byte/length update events are delivered before Complete (no dropped or reordered callbacks)
3. Log m_SavedLength and CurrentLength to identify which counter drifts and under what network conditions

Example fix

// before
onComplete(totalReceived);
// after
if (totalReceived == reportedBytesSum) onComplete(totalReceived); else onError(...);

long reportedSum = /* sum of UpdateBytes/UpdateLength reported bytes */; if (reportedSum != expectedTotal) helperCallbackOnError();

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(); }

When it happens

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

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

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Offset is invalid.
• Length is invalid.
• Delta length is invalid.
• Download agent helper is invalid.
• Task is invalid.

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

Appendix: source

Thrown at GameFramework/Download/DownloadManager.DownloadAgent.cs:326

            }

            private void OnDownloadAgentHelperUpdateLength(object sender, DownloadAgentHelperUpdateLengthEventArgs e)
            {
                m_WaitTime = 0f;
                m_DownloadedLength += e.DeltaLength;
                if (DownloadAgentUpdate != null)
                {
                    DownloadAgentUpdate(this, e.DeltaLength);
                }
            }

            private void OnDownloadAgentHelperComplete(object sender, DownloadAgentHelperCompleteEventArgs e)
            {
                m_WaitTime = 0f;
                m_DownloadedLength = e.Length;
                if (m_SavedLength != CurrentLength)
                {
                    throw new GameFrameworkException("Internal download error.");
                }

                m_Helper.Reset();
                m_FileStream.Close();
                m_FileStream = null;

                if (File.Exists(m_Task.DownloadPath))
                {
                    File.Delete(m_Task.DownloadPath);
                }

                File.Move(Utility.Text.Format("{0}.download", m_Task.DownloadPath), m_Task.DownloadPath);

                m_Task.Status = DownloadTaskStatus.Done;

                if (DownloadAgentSuccess != null)
                {
                    DownloadAgentSuccess(this, e.Length);

View on GitHub (pinned to d0c010b051)