MonadError: Handling Errors Gracefully
Raise an error as a value, and recover from it, in any container whose instance has an error type.
"the test of a first-rate intelligence is the ability to hold two opposed ideas in the mind at the same time, and still retain the ability to function."
— F. Scott Fitzgerald, The Crack-Up
A chain that can fail holds two paths in mind at once: the one where every step succeeds, and the one where a step goes wrong. MonadError writes both in the same code.
- Say why a typed error travels where an exception cannot
- Raise an error as a value with
raiseError, in one method for any container - Name each instance's error type, and what
raiseErrorbuilds in it - Choose among
handleErrorWith,handleError,recoverandrecoverWith, and say which builds its fallback first - State the three laws that tie raising to handling
The code on this page is MonadErrorBook.java: the page includes it, so the build compiles and runs it. MonadErrorBookTest.java holds what the page says each instance does, and FoundationsLawsBookTest.java checks the laws.
When an exception is not enough
An exception does one job well: a method throws, and a caller that can act catches. A few flat try blocks with early returns handle most code. The trouble starts when a failure has to travel through code that was not written for it. A checked exception cannot leave the lambda passed to map:
List<Order> orders = ids.stream().map(id -> findOrThrow(id)).toList();
javac refuses it with "unreported exception OrderNotFoundException". An unchecked exception gets through, but then nothing in the signature says what can fail. A typed error is a value instead: it sits in the return type, and passes through map and flatMap as any value does. With find returning an Either<String, Order>, the same lambda compiles, and each missing order is a Left in the list:
List<Either<String, Order>> orders = ids.stream().map(id -> find(id)).toList();
You already raise and recover with values on one container:
CompletableFuture.failedFuture(new OrderNotFoundException(id)); // an error as a value
future.exceptionallyCompose(error -> fetchFromArchive(id)); // recover with another future
future.exceptionally(error -> placeholder); // recover with a plain value
MonadError names those three for any container: raiseError, handleErrorWith and handleError.
For one container, an Effect Path carries its error in its type, and recovers with its own methods, such as EitherPath's recover and recoverWith, which take a function of the error. On MonadError the same two names take a fixed value, as The same names on a Path shows. Application code stays on the Paths. This page is for a method written once for any container with an error type.
The code on this page uses these imports, with Order from the order records the Optics chapter introduces:
import static org.higherkindedj.hkt.either.EitherKindHelper.EITHER;
import static org.higherkindedj.hkt.instances.Witnesses.either;
import static org.higherkindedj.hkt.instances.Witnesses.maybe;
import static org.higherkindedj.hkt.instances.Witnesses.try_;
import static org.higherkindedj.hkt.maybe.MaybeKindHelper.MAYBE;
import static org.higherkindedj.hkt.trymonad.TryKindHelper.TRY;
import org.higherkindedj.example.book.optics.cast.Order;
import org.higherkindedj.example.book.optics.cast.OrderStatus;
import org.higherkindedj.hkt.Kind;
import org.higherkindedj.hkt.MonadError;
import org.higherkindedj.hkt.TypeArity;
import org.higherkindedj.hkt.Unit;
import org.higherkindedj.hkt.WitnessArity;
import org.higherkindedj.hkt.either.Either;
import org.higherkindedj.hkt.either.EitherKind;
import org.higherkindedj.hkt.instances.Instances;
import org.higherkindedj.hkt.maybe.Maybe;
import org.higherkindedj.hkt.maybe.MaybeKind;
import org.higherkindedj.hkt.trymonad.Try;
import org.higherkindedj.hkt.trymonad.TryKind;
What a MonadError adds
MonadError<F, E> extends Monad<F> with two methods, where E is the instance's error type:
public interface MonadError<F extends WitnessArity<TypeArity.Unary>, E> extends Monad<F> {
<A> Kind<F, A> raiseError(E error);
<A> Kind<F, A> handleErrorWith(Kind<F, A> ma, Function<? super E, ? extends Kind<F, A>> handler);
// abridged: handleError, recover and recoverWith are default methods
// built on handleErrorWith
}
raiseError builds a failed value. Nothing is thrown, and every instance refuses a null error. handleErrorWith runs handler on a failure, and passes a success on unchanged. The handler gives back a container of its own, so a recovery can fail too.
One method for any container
refuseShipped is written over MonadError, as totalUnlessShipped on Working with Kind is, without the total. It takes the MonadError for F and the error to raise, so it never needs to know what an error is in F:
// One method for any container F whose errors are E: refuse an order that has shipped
public static <F extends WitnessArity<TypeArity.Unary>, E> Kind<F, Order> refuseShipped(
MonadError<F, E> monadError, Kind<F, Order> found, E shipped) {
return monadError.flatMap(
order ->
order.status() == OrderStatus.SHIPPED
? monadError.raiseError(shipped)
: monadError.of(order),
found);
}
flowchart TD
accTitle: Where refuseShipped raises an error
accDescr: The found value is tested. If it is already an error, flatMap passes that error on. If it holds an order that has not shipped, the order goes on as a value. A shipped order becomes the error that raiseError builds.
F["found"] --> A{"already an error?"}
A -->|"yes"| P["that error, passed on"]
A -->|"no"| S{"shipped?"}
S -->|"no"| V["of(order): a value"]
S -->|"yes"| R["raiseError(shipped): a new error"]
classDef step fill:#8caaee,stroke:#1e66f5,color:#232634
classDef decision fill:#e5c890,stroke:#df8e1d,color:#232634
classDef ok fill:#a6d189,stroke:#40a02b,color:#232634
classDef error fill:#e78284,stroke:#d20f39,color:#232634
class F step
class A,S decision
class V ok
class P,R error
The diagram shows that only a shipped order becomes a new error. A caller's handleErrorWith can replace either error. Run it on an order that has shipped, with Either's instance, then Try's, then Maybe's. SHIPPED is any Order whose status is SHIPPED:
MonadError<EitherKind.Witness<String>, String> eitherMonadError =
Instances.monadError(either());
Either<String, Order> refused =
EITHER.narrow(
refuseShipped(
eitherMonadError, EITHER.widen(Either.right(SHIPPED)), "order has shipped"));
// Left(order has shipped)
MonadError<TryKind.Witness, Throwable> tryMonadError = Instances.monadError(try_());
Try<Order> failed =
TRY.narrow(
refuseShipped(
tryMonadError,
TRY.widen(Try.success(SHIPPED)),
new IllegalStateException("order has shipped")));
// Failure(java.lang.IllegalStateException: order has shipped)
MonadError<MaybeKind.Witness, Unit> maybeMonadError = Instances.monadError(maybe());
Maybe<Order> nothing =
MAYBE.narrow(
refuseShipped(maybeMonadError, MAYBE.widen(Maybe.just(SHIPPED)), Unit.INSTANCE));
// Nothing
The call is the same each time, and the error is the instance's: a String for this Either, a Throwable for Try, and Unit for Maybe. Unit is a type with one value, because Nothing carries no detail.
What each instance does
MonadError promises that handleErrorWith runs its handler on what raiseError built, and leaves a success alone. What an error is, and when the handler runs, is each instance's own:
| Instance | Its error type E | raiseError(e) gives | handleErrorWith runs the handler |
|---|---|---|---|
Either<L, A> | L | Left(e) | On a Left |
Validated<E, A> | E | Invalid(e) | On an Invalid |
Try | Throwable | Failure(e) | On a Failure. An exception the handler throws becomes a Failure too |
Maybe, Optional | Unit | Nothing, or an empty Optional | On Nothing or an empty Optional, with Unit.INSTANCE |
CompletableFuture | Throwable | A future that has failed with e | When the future fails, with the cause unwrapped from any CompletionException |
VTask | Throwable | A task that fails with e when it runs | When the task fails, as it runs |
IO, List, Writer, State and Reader have no MonadError. An IO that fails throws its exception when it runs, and an IOPath recovers with its own handleError.
Recovering
Four methods recover from an error, and handleErrorWith is the one the others are built on:
| Method | What it does | Built as |
|---|---|---|
handleErrorWith(ma, handler) | Runs handler on the error, for a recovery that can itself fail | The instance's own |
handleError(ma, handler) | Runs handler on the error, for a plain value | handleErrorWith(ma, error -> of(handler.apply(error))) |
recoverWith(ma, fallback) | Swaps a failure for fallback, a container built before the call | handleErrorWith(ma, error -> fallback) |
recover(ma, value) | Swaps a failure for value | handleError(ma, error -> value) |
Store holds one order, gives a Left with its own message for any other id, and counts its reads. live holds ORDER, archive holds ARCHIVED, and MISSING is an id neither holds. handleErrorWith reads the archive only when the live store fails. handleError's handler gives a value of the source's own type, so map first turns the order into the report's String:
Store live = new Store(ORDER, "not in the live store");
Store archive = new Store(ARCHIVED, "not in the archive");
Either<String, Order> fromArchive =
EITHER.narrow(
eitherMonadError.handleErrorWith(
live.find(ARCHIVED.id()), _ -> archive.find(ARCHIVED.id())));
// Right(Order[id=00000000-0000-0000-0000-000000000003, ...])
Either<String, Order> nowhere =
EITHER.narrow(
eitherMonadError.handleErrorWith(live.find(MISSING), _ -> archive.find(MISSING)));
// Left(not in the archive)
Either<String, String> report =
EITHER.narrow(
eitherMonadError.handleError(
eitherMonadError.map(order -> "found", live.find(MISSING)),
error -> "no order: " + error));
// Right(no order: not in the live store)
Should you use recoverWith or handleErrorWith?
A ticket like this one: the order service reads each order from its live store, and falls back to the archive when the order is not there. The line is monadError.recoverWith(live.find(id), archive.find(id)). Every request now reads the archive too, because Java evaluates archive.find(id) before recoverWith is called, whether the live store finds the order or not. The archive starts throttling the service, and its read count climbs to match the live store's. The tests stub the archive and check only the result, which is correct; none of them counts the archive's reads.
The fix gives the archive read to a handler, which runs only on a failure. For an order the live store holds, recoverWith reads the archive once, and the handler never does:
Store readFirst = new Store(ARCHIVED, "not in the archive");
Kind<EitherKind.Witness<String>, Order> withFallback =
eitherMonadError.recoverWith(live.find(ORDER.id()), readFirst.find(ORDER.id()));
int archiveReadsWithRecoverWith = readFirst.reads();
// 1
Store readOnFailure = new Store(ARCHIVED, "not in the archive");
Kind<EitherKind.Witness<String>, Order> withHandler =
eitherMonadError.handleErrorWith(
live.find(ORDER.id()), _ -> readOnFailure.find(ORDER.id()));
int archiveReadsWithAHandler = readOnFailure.reads();
// 0
recoverWith and recover take a value, so Java builds it before the call, whether the source fails or not. Pass them a fallback that is already built, or cheap to build. When building it costs a read, a call or any other effect, use handleErrorWith, whose handler runs only on a failure.
The two shortcuts treat null differently, as What the shortcuts do with null shows.
Three laws
A MonadError keeps the three monad laws, and three more that tie raising to handling. Together they say that a handler sees exactly the error raised and never a success, and that no step runs on an error.
- Handling a raised error is the handler.
handleErrorWith(raiseError(e), handler)equalshandler.apply(e). - A success is never handled.
handleErrorWith(of(a), handler)equalsof(a). - A raised error skips every step.
flatMap(f, raiseError(e))equalsraiseError(e).
Two containers are equal when they hold equal values, or equal errors, in the same shape. For a deferred container such as VTask, they are equal when running both gives equal results or the same error. The laws assume values and errors that are never null, and functions that never return one, and Values, never null says what each type does with one.
Checking these three laws with an hkj-test helper is not supported yet. The test checks them by hand on Either, Try and Maybe, with an equality from KindEquivalence.byEqualsAfter that unwraps both sides and compares them with equals. Its first handler gives back the error it receives, so the first law fails if an instance hands the handler a different error. ORDER is any Order, and the test uses these imports, with JUnit's:
import static org.assertj.core.api.Assertions.assertThat;
import static org.higherkindedj.hkt.either.EitherKindHelper.EITHER;
import static org.higherkindedj.hkt.instances.Witnesses.either;
import static org.higherkindedj.hkt.instances.Witnesses.maybe;
import static org.higherkindedj.hkt.instances.Witnesses.try_;
import static org.higherkindedj.hkt.maybe.MaybeKindHelper.MAYBE;
import static org.higherkindedj.hkt.trymonad.TryKindHelper.TRY;
import java.util.function.BiPredicate;
import java.util.function.Function;
import org.higherkindedj.example.book.optics.cast.Customer;
import org.higherkindedj.example.book.optics.cast.Order;
import org.higherkindedj.hkt.Kind;
import org.higherkindedj.hkt.MonadError;
import org.higherkindedj.hkt.TypeArity;
import org.higherkindedj.hkt.Unit;
import org.higherkindedj.hkt.WitnessArity;
import org.higherkindedj.hkt.assertions.KindEquivalence;
import org.higherkindedj.hkt.either.EitherKind;
import org.higherkindedj.hkt.instances.Instances;
import org.higherkindedj.hkt.maybe.MaybeKind;
import org.higherkindedj.hkt.trymonad.TryKind;
<F extends WitnessArity<TypeArity.Unary>, E> void assertMonadErrorLaws(
MonadError<F, E> monadError, E error, BiPredicate<Kind<F, ?>, Kind<F, ?>> same) {
Function<E, Kind<F, E>> giveBackTheError = monadError::of;
Function<E, Kind<F, String>> handled = raised -> monadError.of("handled");
Function<Order, Kind<F, Customer>> findCustomer = order -> monadError.of(order.customer());
// handling a raised error is the handler, given that same error
assertThat(
same.test(
monadError.handleErrorWith(monadError.<E>raiseError(error), giveBackTheError),
giveBackTheError.apply(error)))
.isTrue();
// a success is never handled
assertThat(
same.test(
monadError.handleErrorWith(monadError.of("kept"), handled), monadError.of("kept")))
.isTrue();
// a raised error skips every step
assertThat(
same.test(
monadError.flatMap(findCustomer, monadError.<Order>raiseError(error)),
monadError.raiseError(error)))
.isTrue();
}
@Test
@DisplayName("Either's, Try's and Maybe's MonadError keep the laws that tie raising to handling")
void monadErrorLaws() {
MonadError<EitherKind.Witness<String>, String> eitherErrors = Instances.monadError(either());
MonadError<TryKind.Witness, Throwable> tryErrors = Instances.monadError(try_());
MonadError<MaybeKind.Witness, Unit> maybeErrors = Instances.monadError(maybe());
assertMonadErrorLaws(
eitherErrors,
"order not found",
KindEquivalence.<EitherKind.Witness<String>>byEqualsAfter(EITHER::narrow));
assertMonadErrorLaws(
tryErrors,
new IllegalStateException("order not found"),
KindEquivalence.<TryKind.Witness>byEqualsAfter(TRY::narrow));
assertMonadErrorLaws(
maybeErrors,
Unit.INSTANCE,
KindEquivalence.<MaybeKind.Witness>byEqualsAfter(MAYBE::narrow));
}
Things people get wrong
- "
raiseErrorthrows an exception." It builds a value that holds the error. Nothing is thrown, andflatMappasses the error on without running its step. - "
handleErrorWithand a try/catch are the same." They look alike, and work differently. Acatchruns when the call stack unwinds;handleErrorWithis a method call on a value, so it composes withmapandflatMap. - "You have to use
Either." Any instance with aMonadErrorworks:Either,Validated,Try,Maybe,Optional,CompletableFuture,VTask, and theEitherT,MaybeTandOptionalTtransformers. An Effect Path recovers through its own methods. - "Recovery is for the end of the chain." It can sit anywhere. A
handleErrorWithbetween twoflatMapcalls retries one step before the chain goes on. - "
recoverWithruns only on a failure." It takes a value, so Java builds its fallback first: that is how the ticket's archive was read on every request.
You can now raise an error as a value in a method written once for any container, as refuseShipped is, and name each instance's error type. You can recover with the right one of four methods, keeping a costly fallback in a handler, and state the three laws that tie raising to handling. The rest of this page is for which types have a MonadError, the different meaning of the same names on a Path, and what builds on MonadError.
Does Instances.monadError(vtask()).raiseError(error) throw error?
Answer and why
Answer and why
No. It builds a task that fails with error when it runs, and nothing is thrown until then. raiseError builds a value in every instance; VTask's value is a task.
Where this lives: What each instance does.
found is a success. In monadError.recover(found, slowDefault()), does slowDefault() run?
Answer and why
Answer and why
Yes. recover takes a value, so Java calls slowDefault() before recover, whatever found holds. To run it only on a failure, give it to a handler: handleError(found, _ -> slowDefault()).
Where this lives: Should you use recoverWith or handleErrorWith?
The fine print
Which types have a MonadError
| Types | Their MonadError comes from |
|---|---|
Either, Try, Maybe, Optional, CompletableFuture, VTask | Instances.monadError(token) |
Validated | Instances.validated(semigroup) |
EitherT, MaybeT, OptionalT, whose errors are L, Unit and Unit | Instances.eitherT(outer), Instances.maybeT(outer) and Instances.optionalT(outer) |
IO, List, Writer, State, Reader and the other transformers | Nowhere: they have none |
Instances.monadError(token) casts the token's Monad, and the compiler can check neither that cast nor E. What the compiler checks says what fails, and when.
The same names on a Path
An EitherPath recovers with methods that share two names with MonadError, and mean something else:
| What you want | On MonadError | On an EitherPath |
|---|---|---|
| A value from the error | handleError(ma, error -> a) | path.recover(error -> a) |
| Another container from the error | handleErrorWith(ma, error -> mb) | path.recoverWith(error -> otherPath) |
| A fixed value | recover(ma, a) | path.recover(_ -> a) |
| A fixed fallback, built only on a failure | handleErrorWith(ma, _ -> mb) | path.orElse(() -> otherPath) |
| A fallback already built | recoverWith(ma, mb) | path.recoverWith(_ -> otherPath) |
So on a Path, recover and recoverWith take a function of the error, which runs only on a failure. On MonadError, they take a fixed value, which Java builds first.
What the shortcuts do with null
recoverWith refuses a null fallback, and a null source, at the call on every instance in the library, so a null fallback fails there and not later inside handleErrorWith. Each instance overrides recoverWith to check; an instance you write that keeps the default checks nothing. recover refuses a null source too, and leaves a null value to of:
| Instances | recover(ma, null) |
|---|---|
Maybe, Optional, MaybeT, OptionalT | Gives Nothing or an empty Optional |
CompletableFuture | Holds the null |
Either, Try, VTask, EitherT | Refuses it at the call, whatever the source holds, because a success always holds a value |
Validated | Refuses it only when the source is invalid |
What builds on MonadError
GenericPathtakes one.GenericPath.of(kind, monadError)gives a Path over anyKindthat can recover, with the Path meanings ofrecoverandrecoverWith, as GenericPath shows.- Three transformers have one.
EitherT,MaybeTandOptionalTraise and recover in their own error type over any outerMonad, as Monad Transformers shows.
- Monad: the type class
MonadErrorextends - Either: the instance most code uses for a typed error
- Try: the instance whose error is a
Throwable - EitherPath: recovery on a Path, for one container
- One Line, Six Layers:
path.recoverbesidehandleError
- Typelevel, ApplicativeError and MonadError: the same type class in Scala's Cats library
- Mark Seemann, An Either monad:
Eitheras a monad for errors, with examples in C#, F# and Haskell
Practise error handling in Tutorial 05: Monad Error Handling (7 exercises).
Previous: Monad Next: For Comprehension