Flutter Network Errors: Fail Gracefully

Why it exists

Mobile networks are inherently unreliable. A user might step into an elevator, switch from WiFi to cellular, or hit a flaky captive portal. If your Flutter app assumes every request succeeds, the result is either a crashed app from an unhandled exception or a frozen UI that leaves the user staring at a spinner. Network error handling exists to turn these inevitable failures into controlled, recoverable states.

The mental model

Think of your app as a ship and the network as the ocean. You cannot calm the ocean, but you can build bulkheads. The UI layer should never feel the spray of a SocketException directly. Instead, a middle layer, the repository or service, absorbs the impact and translates it into something the presentation layer understands: a sealed Result type with states like Success, Offline, or ServerError. This separation means your widgets worry about what to show, not how to parse a stack trace.

How it works

In practice, you wrap your HTTP calls, whether using the http package, Dio, or GraphQL, in a try-catch block inside a dedicated service class. Catch platform-level exceptions like SocketException and TimeoutException first. Then inspect HTTP status codes: 4xx errors usually mean client mistakes or auth issues, while 5xx signals server trouble. Map each failure category to a domain-specific error enum. Return this enum inside a Result wrapper to your BLoC, Riverpod notifier, or UI. Never return raw Response objects or exceptions to the widget layer.

When to use it

Use this pattern on every network boundary in production apps. It is essential when building offline-first experiences, retry mechanisms, or any screen that displays remote data. If you are showing a feed, a checkout flow, or a search result, the user needs a graceful fallback when the signal drops.

When not to use it

Do not wrap every function indiscriminately. Local database writes, file I/O on device storage, or pure Dart computations should use different error models. Also avoid swallowing errors silently in development; you need visibility into failures during debugging, so log aggressively even if you suppress the crash in release.

One canonical example

A news app fetches headlines with Dio. The repository catches a SocketException when the user enters a tunnel and maps it to a NetworkFailure.offline state. The Riverpod provider watching this request emits an AsyncError with that domain error. The UI switches from a loading shimmer to an offline banner with a Retry button. The user taps Retry, the provider refetches, and the list populates without ever restarting the app.