Flutter error handling is about more than catching exceptions. It’s about turning failures into clear, calm user experiences while still giving developers enough detail to debug. This playbook walks through patterns for surfacing errors in the UI, logging them safely, and wiring everything into a predictable flow.
Audience: IntermediateTested on: Flutter 3.x, Dart 3.x, macOS 14 / Windows 11, Android 14 / iOS 17
Designing an error handling strategy
Before writing any code, decide what happens when things go wrong:
- What does the user see? A toast, inline message, full-screen error, or silent retry?
- What do you log? Context, stack trace, user ID, environment?
- What can the user do? Retry, go back, report the issue, or continue offline?
A good rule of thumb is: “actionable message for the user, detailed data for developers.” Don’t expose raw exception messages directly to users.
A simple Result type for async operations
Instead of throwing from every repository method, wrap results in a small sealed type. It keeps UI code clean and makes error states explicit.
// lib/shared/result.dart
sealed class Result<T> {
const Result();
}
class Success<T> extends Result<T> {
final T value;
const Success(this.value);
}
class Failure<T> extends Result<T> {
final Object error;
final StackTrace stackTrace;
const Failure(this.error, this.stackTrace);
}
// Example usage in a repository
Future<Result<User>> fetchUserProfile() async {
try {
final response = await _client.get(...);
final user = User.fromJson(response.data);
return Success(user);
} catch (e, st) {
_logger.error('fetchUserProfile failed', e, st);
return Failure(e, st);
}
}
Mapping technical errors to UX-friendly messages
The UI should not care about low-level exceptions like SocketException. Introduce a mapper that converts errors into a small set of user-facing categories.
// lib/shared/error_presenter.dart
enum UiErrorType { network, timeout, validation, unknown }
class UiError {
final UiErrorType type;
final String message;
final String? debugId; // log correlation ID
UiError(this.type, this.message, {this.debugId});
}
UiError toUiError(Object error) {
// Example: very simplified
if (error.toString().contains('SocketException')) {
return UiError(
UiErrorType.network,
'Network error. Please check your connection and try again.',
);
}
if (error.toString().contains('TimeoutException')) {
return UiError(
UiErrorType.timeout,
'This is taking longer than expected. Please try again.',
);
}
return UiError(
UiErrorType.unknown,
'Something went wrong. Please try again later.',
);
}
In your view models or controllers, convert Failure into UiError and expose that to the widget tree.
Presenting errors in the UI
Use different patterns depending on how critical the failure is:
- Inline error text for field validation: show messages near the input.
- Snackbars for transient, non-blocking failures (e.g., “Failed to refresh. Tap to retry.”).
- Full-screen error states when a screen cannot load at all.
// Example: full-screen error with retry
class ErrorView extends StatelessWidget {
final String message;
final VoidCallback onRetry;
const ErrorView({super.key, required this.message, required this.onRetry});
@override
Widget build(BuildContext context) {
return Center(
child: Padding(
padding: const EdgeInsets.all(24),
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
const Icon(Icons.error_outline, size: 48),
const SizedBox(height: 16),
Text(
message,
textAlign: TextAlign.center,
),
const SizedBox(height: 24),
FilledButton(
onPressed: onRetry,
child: const Text('Retry'),
),
],
),
),
);
}
}
Centralized logging and crash reporting
You’ll want a single place where errors are logged and forwarded to your crash/analytics service (for example, Sentry or Firebase Crashlytics). Wrap that in an interface so tests can swap it out.
abstract class AppLogger {
void info(String message, [Object? data]);
void warn(String message, [Object? data]);
void error(String message, Object error, StackTrace stackTrace);
}
class CrashlyticsLogger implements AppLogger {
@override
void error(String message, Object error, StackTrace stackTrace) {
// Pseudocode; integrate with your crash tool of choice.
// FirebaseCrashlytics.instance.recordError(error, stackTrace, reason: message);
}
@override
void info(String message, [Object? data]) {/* ... */}
@override
void warn(String message, [Object? data]) {/* ... */}
}
In main(), set up your logger and pass it through dependency injection so repositories and view models can use it without knowing about the concrete implementation.
Global error handlers in Flutter
Some errors never touch your repository layer, such as uncaught framework errors. Configure global handlers to log them and display a safe fallback UI instead of a crash.
void main() {
final logger = CrashlyticsLogger();
FlutterError.onError = (details) {
logger.error('Flutter framework error', details.exception, details.stack ?? StackTrace.empty);
FlutterError.presentError(details);
};
runZonedGuarded(
() {
runApp(const MyApp());
},
(error, stack) {
logger.error('Uncaught zone error', error, stack);
},
);
}
Be careful not to hide serious issues silently. Critical errors should still fail loudly during development; you can toggle stricter behavior in debug builds.
Security & common pitfalls
- Leaking sensitive data: Never send full request bodies, access tokens, or personal user data in logs or crash reports. Log IDs and hashes instead of raw values.
- Showing raw exception text: Messages like “SocketException: Failed host lookup” are confusing and can leak internals. Always map to friendly, localized strings.
- Infinite retry loops: Automatic retries should be capped and backed off; otherwise you risk hammering APIs and draining battery.
- Ignoring timeouts: Always set timeouts on network calls so UI doesn’t hang forever; handle those with clear “This is taking too long” messages.
Testing your error flows
Write tests that deliberately fail repositories and verify how the UI reacts.
testWidgets('shows error view when loading fails', (tester) async {
final failingRepo = FakeUserRepo(
result: Failure(Exception('boom'), StackTrace.current),
);
await tester.pumpWidget(buildTestApp(repo: failingRepo));
await tester.pumpAndSettle();
expect(find.textContaining('Something went wrong'), findsOneWidget);
expect(find.text('Retry'), findsOneWidget);
});
Also test global handlers by simulating framework errors in integration tests where possible, ensuring that logs are sent and the app does not stay in a broken state.
FAQ
Q: Should I always wrap results instead of throwing?
A: For network and domain errors, returning a Result type often makes UI flows clearer. For truly exceptional programming mistakes, throwing (and letting global handlers/logging catch them) is still appropriate.
Q: How verbose should user-facing messages be?
A: Keep them short, neutral, and actionable: “Check your connection and try again” is better than a long technical explanation. Use logs and crash reports for detailed diagnostics.
Q: Should all errors show a dialog?
A: No. Dialogs are disruptive. Prefer inline errors or snackbars for minor issues and reserve dialogs/full-screen states for blocking failures.
Conclusion
Effective Flutter error handling means planning for failure: explicit result types, clear UI messaging, centralized logging, and global handlers for unexpected crashes. When you separate technical details from user-facing messages and cover both with tests, failures become predictable—and your app feels much more trustworthy.
Updated: 2025-10-30
Comment