/flutter-error-handling

name: flutter-error-handling
description: Implement functional repository error recovery with Either/Failure patterns in Flutter. Use when handling exceptions or dartz Either types in data flows; defer UI-only retry buttons.
metadata:
  triggers:
    files:
    - 'lib/domain/**'
    - 'lib/infrastructure/**'
    keywords:
    - Either
    - fold
    - Left
    - Right
    - Failure
    - dartz

Error Handling

**Priority: P1 (HIGH)**

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 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

• **No Try-Catch in BLoC**: BLoC receives `Either` and `folds`; try/catch belongs in Infrastructure
• **No Plain String Failures**: Define typed `@freezed` Failure subclasses instead of `Left('Something went wrong')`
• **No Empty Catch Blocks**: Always log and propagate; never swallow errors silently
• **No Repositories Throwing Status**: Return `Left(Failure)` instead of throwing `Exception`
• **No Missing Log Registration**: Use `AppLogger.error` in BLoC/UI `catch` to ensure Crashlytics tracking and type-safe UI messages

Related Topics

layer-based-clean-architecture | bloc-state-management

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

• TRObject