Flutter error handling

Error Handling

Priority: P1 (HIGH)

Standardized functional error handling using dartz and freezed failures.

Implementation Guidelines

• Either Pattern: Return Either<Failure, T> from repositories. No exceptions in UI/BLoC.
• Failures: Define domain-specific failures using @freezed unions (e.g., UnauthorizedFailure, OutOfStockFailure).
• Mapping: Infrastructure catches Exception (e.g., DioException) and returns Left(Failure). Never rethrow to UI.
• Consumption: Use .fold(failure, success) in BLoC to emit corresponding states. Remove try/catch from BLoC.
• Typed Errors: Use left(Failure()) and right(Value()) from Dartz.
• Low-Cardinality Logging: Use stable message templates; pass variable data via metadata/context.
• Layer Restriction: try/catch only in Infrastructure. UI/Application/BLoC layers should not catch.
• Localization: Use failure.failureMessage (returns TRObject or localized string) for UI-safe text.
• Right/Left Restriction: Only Infrastructure may construct Right()/Left().
• No Silent Catch: Never swallow errors without logging or a documented retry.

Reference & Examples

For Failure definitions and API error mapping: See 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

Related Topics

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