Flutter Smart Error Handler #

A powerful and customizable error handler for Flutter applications. It automatically catches and categorizes errors (Network, Auth, Server, etc.) and displays beautiful Lottie animations or custom images.

Features #

• 🚀 Global Error Handling: Catches both build-time (Red Screen) and async errors.
• 🧐 Smart Categorization: Automatically detects error types like Network, Auth, Storage, etc.
• 🎨 Beautiful UI: Shows specific Lottie animations for each error type.
• 🛠 Fully Customizable: Use your own assets, colors, and text styles.
• 🌐 Cross-Platform: Works on Android, iOS, Web, Windows, etc.

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_smart_error_handler: 
    path: ../ # Or git url / pub version
  lottie: ^3.0.0

Usage #

1. Basic Setup #

Initialize the handler in your main() function.

import 'package:flutter/material.dart';
import 'package:flutter_smart_error_handler/flutter_smart_error_handler.dart';

void main() {
  // Initialize the global error handler
  GlobalErrorHandler.initialize();
  
  runApp(const MyApp());
}

2. Handling Async Errors (Recommended) #

To handle errors that happen outside the UI (like API calls in a button press), you must provide a navigatorKey. This allows the handler to push the error screen from anywhere.

final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

void main() {
  GlobalErrorHandler.initialize(navigatorKey: navigatorKey);
  
  runApp(MaterialApp(
    navigatorKey: navigatorKey, // <--- Don't forget this!
    home: MyApp(),
  ));
}

3. Customization & Logging #

You can customize the look, feel, and logging behavior.

GlobalErrorHandler.initialize(
  navigatorKey: navigatorKey,
  // 1. Logging: Hook into Crashlytics or Sentry
  onLog: (error, stack) {
    // FirebaseCrashlytics.instance.recordError(error, stack);
  },
  // 2. Custom Config
  config: ErrorHandlerConfig()
    ..backgroundColor = Colors.white // Optional: defaults to Theme background
    ..customLottieMap = {
      ErrorType.network: Lottie.asset('assets/no_internet.json'),
    },
);

4. Manual Triggers (NEW!) #

Sometimes you want to show an error screen without throwing an exception.

// Show a specific error type
ErrorHandler.network(message: "Wifi disconnected");
ErrorHandler.auth(message: "Session expired");
ErrorHandler.server();

// Show a generic error
ErrorHandler.show(title: "Oops", message: "Something went wrong");

Supported Error Types #

The package automatically detects:

• ErrorType.network (Timeout, No Connection)
• ErrorType.auth (401, 403, Token Expired)
• ErrorType.backend (500, 503 Server Errors)
• ErrorType.device (Permissions, Camera)
• ErrorType.storage (Disk Full)
• ErrorType.input (Validation)
• ErrorType.appLogic
• ErrorType.update
• ErrorType.payment

Example #

Check the example folder for a complete demo application.