Circuit Breaker Panel with lagom

Table of contents
Reading Time: 2 minutes

Up to v1.3.x, you could use circuit breaker pattern with lagom only in service descriptor usually. To apply circuit breaker to some arbitrary API you had to generally use the underlying akka circuit breaker . How to use circuit breaker with unmanaged services is explained pretty well at  and if you want to poke around with the underlying akka circuit breaker you can take a look at

To use a circuitbreaker with some arbitrary API ( for e.g. a database API like couchbase) with lagom 1.4.x you can use CircuitBreakerPanel. The sole method in this class allows you to write code like –

With correct configuration defined for “circuit-breaker-name”, you can leverage the circuit breaker pattern easily with arbitrary API calls. If your CompletionStage throws any error then it counts towards your CircuitBreaker going to an open state.

Now, you might not want your CircuitBreaker to go into an open state for certain type of exceptions ( say there is some sort of validation going inside your CompletionStage). For this, you can whitelist certain exceptions using the field “lagom.circuit-breaker.circuit-breaker-name.exception-whitelist” as shown below –

lagom.circuit-breaker {

  breakerA {
    max-failures = 3
    reset-timeout = 20s
    exception-whitelist = ["java.lang.NullPointerException"]


It accepts an array of strings in which you can define all the exceptions for which you don’t want the circuit breaker to go towards an open state. I have created a minimal example to showcase how to leverage CircuitBreakerPanel along with exception whitelisting at  –

Demo Repo


Written by 

Neelaksh Chauhan is a Software Consultant, with an experience of more than 1 year . He knows Java and python. He is familiar with Object Oriented Programming Paradigms. He is always eager to learn new and advance concepts in order to expand his horizon and apply them in project development with his existing knowledge. His hobbies include reading and playing.