A team shipping a 5.5 MB Python runtime to browsers discovered that 69 % of the errors logged during a recent sprint fell under a single, misleading title, and 89 % of those were actually network timeouts. The mis-reporting sent developers down the wrong debugging path and left a sizable slice of users with silent download failures—a problem any web-app that bundles large assets can soon replicate.

The dashboard misled

The error-tracking system automatically groups incidents by the code location where they first appear. The resulting title looked like a simple bug in the runtime loader, so the sprint was spent hunting code paths that never timed out. When the team sampled the underlying metadata, the true picture emerged: most failures were not bugs at all but stalled network connections that triggered a timeout.

Takeaway: An error title is a convenience, not a diagnosis. Periodically drill into the raw data to verify what the headline actually represents.

The browser connection API gave a placeholder

To avoid dragging slow users through a 5.5 MB download, the developers consulted the browser’s Network Information API (navigator.connection). The API reported a constant 1.7 Mbps bandwidth for every first-time visitor.

Browsers emit a default value when they have no historical data for a new user. That default is a hint, not a definitive speed. When the same placeholder appears for every fresh session, it signals that the API is not yet calibrated for that audience.

Takeaway: Treat any network signal that never varies as a fallback, not as a definitive metric.

One-off snapshots are unreliable

After discarding the unreliable bandwidth hint, the team switched to a different signal that seemed to work in their test suite. One test run passed, but repeating the test three times produced failures each time. Network speed fluctuates continuously. The code had taken a single snapshot, made a permanent decision, and then proceeded even if the connection changed a moment later.

Takeaway: Do not base a permanent action on a single reading of a moving target. Subscribe to change events instead of polling once.

Practical fixes the team implemented

  • Subscribe to connection changes. Instead of reading navigator.connection once, the code now listens for the change event and reacts if bandwidth drops or rises during the download.
  • Add a “no-progress” watchdog. A timer aborts any request that makes no forward progress after a short interval, freeing the browser to retry or fall back.
  • Stop switching CDNs mid-download. Switching the source of a large file on a slow link restarts the transfer from zero, wasting already-received bytes. The download now sticks to the initially chosen CDN for its entire duration.
  • Defer heavy caching work. Tasks that write large amounts of data to the cache are postponed until after the runtime finishes loading, keeping the critical path short.

If your dashboards paint an unnervingly tidy picture, dig deeper. If a network measurement never moves, treat it as a placeholder. And if a single snapshot decides the fate of a multi-megabyte download, you’re betting on a mirage. Those bets show up as silent failures that erode user trust—something no amount of clever code can fully repair after the fact.