Error handling in Dart, especially when working with asynchronous operations and packages like Dio, often becomes chaotic with deeply nested try-catch blocks. As your codebase grows, this traditional approach becomes harder to maintain, test, and reason about. This is particularly true for real-world applications that require handling API responses, chained async operations, and various failure states.
Enter the dartz package and its powerful Either<L, R> type — a better alternative that brings functional programming principles to Dart.
In this blog, we’ll explore how to master functional error handling in Dart using Either in Dart. We’ll go deep into the dartz package, understand how Either works, compare it with traditional try-catch, and integrate it with Dio to handle API errors cleanly and predictably. This post is targeted at medium to expert Dart/Flutter developers looking to level up their error handling game.
🤔 The Problem with Traditional Try-Catch
Dart’s try-catch mechanism provides a way to handle errors, but it introduces a few issues:
- No type safety: Errors can be of any type (including unexpected ones).
- Lack of composability: You can’t easily chain operations with try-catch.
- Tangled control flow: Catching exceptions leads to deeply nested or scattered error logic.
- Testing complexity: Catching vs. throwing exceptions is harder to test than checking for success/failure values.
Here’s a traditional approach using try-catch:
Future<String> loginUser(String email, String password) async {
try {
final response = await dio.post('/login'da, data: {
'email': email,
'password': password,
});
return response.data['token'];
} on DioError catch (e) {
if (e.response?.statusCode == 401) {
throw Exception("Invalid credentials");
} else {
throw Exception("Network error: ${e.message}");
}
} catch (e) {
throw Exception("Unexpected error: $e");
}
}While this works, it doesn’t scale well. The more logic you have, the harder it is to manage errors in a clean way. That’s where Either comes in.
🧩 What is Either in Dart?
The Either<L, R> type from the dartz package is a functional programming construct used to represent a value that can be either a failure (Left<L>) or a success (Right<R>).
This makes it extremely useful for building robust, maintainable systems that handle failure gracefully without exceptions.
🔍 Basic Syntax Example:
Either<String, int> parseNumber(String input) {
final number = int.tryParse(input);
return number == null ? Left('Invalid number') : Right(number);
}Here, the function returns Left('Invalid number') if parsing fails, or Right(42) if it succeeds. This is clearer and safer than throwing exceptions.
🚀 Why Use Either Instead of Try-Catch?
Here’s how Either transforms error handling:
✅ Benefits:
- Composability: Chain validations and async operations without nested try-catch.
- Predictability: All failures are explicit, contained in Left.
- Testability: You can test return values without simulating exceptions.
- Cleaner async error handling: Especially powerful when using Dio for API interactions.
- Declarative logic: Your code reflects business logic, not plumbing.
🔗 Dart Dio Either Integration: Real-World Example
Let’s walk through how to use Dio along with Either for clean API error handling in Dart.
🛠 Step 1: Setup Dio
final dio = Dio(BaseOptions(baseUrl: 'https://api.example.com'));🧪 Step 2: Wrap the API Call in Either
Future<Either<String, Response>> fetchUserProfile() async {
try {
final response = await dio.get('/user/profile');
return Right(response);
} on DioError catch (e) {
return Left('Dio error: ${e.response?.statusCode ?? 0} - ${e.message}');
} catch (e) {
return Left('Unexpected error: $e');
}
}This function returns an Either that represents the success or failure of the API call without throwing any exceptions.
📥 Consuming Either Values
Now let’s see how to use the result of an Either object.
final result = await fetchUserProfile();
result.fold(
(error) => print('Error: $error'),
(data) => print('User profile: ${data.data}'),
);The fold() method forces you to handle both success and failure, ensuring you don’t miss an edge case.
🔁 Chaining Multiple Either Operations
Chaining with flatMap() lets you compose multiple validation or async steps elegantly:
Future<Either<String, String>> login(String email, String password) async {
return validateEmail(email)
.flatMap((_) => validatePassword(password))
.flatMapAsync((_) => loginUser(email, password));
}This avoids the pyramid of doom caused by multiple try-catch blocks and keeps logic linear and clear.
🧠 Common Patterns and Useful Extensions
Here are some patterns and helpers that make working with Either more ergonomic:
1. mapLeft()
Transform the error part of an Either.
result.mapLeft((e) => 'Transformed error: $e');2. toFuture()
Convert Either to Future (throws on Left).
Future<Response> getUser() async =>
(await fetchUserProfile()).toFuture();3. flatMapAsync()
Chain async functions that return Either.
flatMapAsync((data) => anotherApiCall(data));4. getOrElse()
Provide a default value if the result is a failure.
final token = result.getOrElse(() => 'default-token');🛠 Practical Real-Life Use Case: Chained Login with API Call
Future<Either<String, String>> validateEmail(String email) async {
if (email.contains('@')) {
return Right(email);
} else {
return Left('Invalid email');
}
}
Future<Either<String, String>> validatePassword(String password) async {
return password.length >= 6
? Right(password)
: Left('Password too short');
}
Future<Either<String, String>> loginUser(String email, String password) async {
try {
final response = await dio.post('/login', data: {
'email': email,
'password': password,
});
return Right(response.data['token']);
} on DioError catch (e) {
return Left('Login failed: ${e.message}');
}
}
Future<Either<String, String>> loginFlow(String email, String password) async {
return await validateEmail(email)
.flatMapAsync((_) => validatePassword(password))
.flatMapAsync((_) => loginUser(email, password));
}🧪 Testing Functional Error Handling
Functional style makes testing easier since you’re working with values, not exceptions:
test('Login fails on invalid email', () async {
final result = await loginFlow('invalid', 'password123');
expect(result.isLeft(), true);
expect(result.swap().getOrElse(() => ''), 'Invalid email');
});✅ Conclusion
Using Either from the dartz package gives you a powerful, expressive, and test-friendly way to manage errors in Dart. Whether you're dealing with Dio API calls or multi-step validation flows, functional error handling in Dart brings clarity, composability, and robustness to your Flutter code.
Instead of relying on traditional try-catch for every error scenario, shift toward a declarative, predictable model with Either. It leads to fewer bugs, better test coverage, and much cleaner code.
To model the failure side as a closed set of error types, pair Either with Freezed sealed classes.