flutter-error-handling
Implement functional error recovery with Either/Failure patterns. Use when writing repositories, handling exceptions, defining failures, or using Either in any Flutter layer. (triggers: lib/domain/**, lib/infrastructure/**, Either, fold, Left, Right, Failure, dartz)
Best use case
flutter-error-handling is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Implement functional error recovery with Either/Failure patterns. Use when writing repositories, handling exceptions, defining failures, or using Either in any Flutter layer. (triggers: lib/domain/**, lib/infrastructure/**, Either, fold, Left, Right, Failure, dartz)
Teams using flutter-error-handling should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/flutter-error-handling/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How flutter-error-handling Compares
| Feature / Agent | flutter-error-handling | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Implement functional error recovery with Either/Failure patterns. Use when writing repositories, handling exceptions, defining failures, or using Either in any Flutter layer. (triggers: lib/domain/**, lib/infrastructure/**, Either, fold, Left, Right, Failure, dartz)
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Error Handling
## **Priority: P1 (HIGH)**
Standardized functional error handling using `dartz` and `freezed` failures.
## Implementation Workflow
1. **Define failures** — Create domain-specific failures using `@freezed` unions (e.g., `UnauthorizedFailure`, `OutOfStockFailure`).
2. **Return Either** — Repositories return `Either<Failure, T>`. No exceptions in UI/BLoC.
3. **Catch in Infrastructure only** — Infrastructure catches exceptions (e.g., `DioException`) and returns `Left(Failure)`. Never rethrow to UI.
4. **Fold in BLoC** — Use `.fold(failure, success)` in BLoC to emit corresponding states. Remove try/catch from BLoC.
5. **Localize messages** — Use `failure.failureMessage` (returns `TRObject` or localized string) for UI-safe text.
6. **Log with stable templates** — Use low-cardinality message templates; pass variable data via metadata/context.
7. **No Silent Catch**: Never swallow errors without logging or a documented retry.
8. **Crashlytics Routing**: All UI/BLoC `catch` blocks MUST route errors via `AppLogger.error(AppException.fromException(e).message, error: e, stackTrace: st)` for observability and type-safe UI messages.
### Repository & BLoC Examples
See [implementation examples](references/implementation.md) for repository error mapping and BLoC consumption patterns.
## Reference & Examples
For Failure definitions and API error mapping:
See [references/REFERENCE.md](references/REFERENCE.md).
## Anti-Patterns
- ❌ `try { … } catch (e) { emit(ErrorState()); }` in BLoC — try/catch belongs only in Infrastructure; BLoC receives `Either`, then folds
- ❌ `Left(Failure('Something went wrong'))` using a plain `String` — define typed `@freezed` Failure subclasses for each domain error
- ❌ `catch (e) {}` empty catch — always log and propagate; never swallow silently
- ❌ Throwing `Exception` from a repository — return `Left(Failure)` instead; exceptions must not cross the infrastructure boundary
- ❌ `catch (e) { print(e); }` — missing `AppLogger.error`; errors must be sent to Crashlytics with the original error and stack trace
## Related Topics
layer-based-clean-architecture | bloc-state-managementRelated Skills
swift-error-handling
Standards for throwing functions, Result type, and Never. Use when implementing Swift error throwing, designing error hierarchies, using Result types, or adding do-catch blocks. (triggers: **/*.swift, throws, try, catch, Result, Error)
php-error-handling
Implement modern PHP error and exception handling patterns. Use when implementing exception hierarchies, error handlers, or custom exceptions in PHP. (triggers: **/*.php, try, catch, finally, Throwable, set_exception_handler)
nestjs-error-handling
Implement Global Exception Filters and standard error formats in NestJS. Use when implementing global exception filters or standardizing error responses in NestJS. (triggers: **/*.filter.ts, main.ts, ExceptionFilter, Catch, HttpException)
golang-error-handling
Standards for error wrapping, checking, and definition in Golang. Use when wrapping errors, defining sentinel errors, or handling errors idiomatically in Go. (triggers: fmt.Errorf, errors.Is, errors.As, error wrapping, sentinel error, error handling)
flutter-widgets
Build maintainable Flutter UI components with composition and theming. Use when building, refactoring, or reviewing Flutter widget implementations for maintainability. (triggers: **_page.dart, **_screen.dart, **/widgets/**, StatelessWidget, const, Theme, ListView)
flutter-testing
Write unit, widget, and integration tests with robots, widget keys, and Patrol in Flutter. Use when writing Flutter unit tests, widget tests, or integration tests with Patrol. (triggers: **/test/**.dart, **/integration_test/**.dart, **/robots/**.dart, lib/core/keys/**.dart, test, patrol, robot, WidgetKeys, patrolTest, blocTest, mocktail)
flutter-security
Enforce OWASP Mobile security standards for Flutter apps. Use when storing data, making network calls, handling tokens/PII, or preparing a release build. (triggers: lib/infrastructure/**, pubspec.yaml, secure_storage, obfuscate, jailbreak, pinning, PII, OWASP)
flutter-riverpod-state-management
Implement reactive state management using Riverpod 2.0 with code generation in Flutter. Use when defining @riverpod providers, building AsyncNotifiers, overriding providers in tests, or enforcing immutable state with Freezed models. (triggers: **_provider.dart, **_notifier.dart, riverpod, ProviderScope, ConsumerWidget, Notifier, AsyncValue, ref.watch, @riverpod)
flutter-retrofit-networking
Build type-safe HTTP networking with Dio and Retrofit including auth interceptors. Use when integrating Dio, Retrofit, or API auth interceptors in Flutter. (triggers: **/data_sources/**, **/api/**, Retrofit, Dio, RestClient, GET, POST, Interceptor, refreshing)
flutter-performance
Optimization standards for rebuilds and memory. Use when optimizing Flutter widget rebuilds, reducing memory usage, or improving rendering performance. (triggers: lib/presentation/**, pubspec.yaml, const, buildWhen, ListView.builder, Isolate, RepaintBoundary)
flutter-notifications
Integrate push and local notifications using FCM and flutter_local_notifications. Use when adding push or local notifications to Flutter apps. (triggers: **/*notification*.dart, **/main.dart, FirebaseMessaging, FlutterLocalNotificationsPlugin, FCM, notification, push)
flutter-navigation
Implement navigation patterns with go_router, deep linking, and named routes. Use when building navigation, deep linking, or named routes in Flutter. (triggers: **/*_route.dart, **/*_router.dart, **/main.dart, Navigator, GoRouter, routes, deep link, go_router, AutoRoute)