Why Disruptor’s Default ExceptionHandler Crashes Your QPS and How to Fix It

While building a new performance‑testing model with the Disruptor library, the author observed that QPS gradually fell to zero after a series of exceptions, eventually stopping all processing.

The root cause lies in the com.lmax.disruptor.ExceptionHandler interface, which handles exceptions that occur while consuming messages. The relevant code is in com.lmax.disruptor.WorkProcessor#run and includes a catch block like:

catch (final Throwable ex) {
    // handle, mark as processed, unless the exception handler threw an exception
    exceptionHandler.handleEventException(ex, nextSequence, event);
    processedSequence = true;
}

When the default handler is used, Disruptor employs com.lmax.disruptor.FatalExceptionHandler. Its handleEventException method logs the error and then throws a RuntimeException:

@Override
public void handleEventException(final Throwable ex, final long sequence, final Object event) {
    logger.log(Level.SEVERE, "Exception processing: " + sequence + " " + event, ex);
    throw new RuntimeException(ex);
}

This re‑throw causes the WorkProcessor to fail; if many consumer exceptions occur, the consumer threads are quickly terminated, leaving no thread to process events.

To prevent this, the author recommends not using the default fatal handler. Instead, one can switch to one of Disruptor’s built‑in handlers such as com.lmax.disruptor.IgnoreExceptionHandler or Log4j’s

org.apache.logging.log4j.core.async.AsyncLoggerDefaultExceptionHandler

, which merely log the exception. The author also provides a simple custom handler (the code snippet is illustrative) to illustrate how to swallow exceptions without killing the thread.

try {
    dosomething()
} catch (e) {
    // custom handling logic
}

Because the error rate rises with higher QPS, logging every exception can itself generate a significant amount of error traffic (e.g., 10+ QPS of error logs at a 0.0001 error probability). The author suggests aggregating such exceptions in a dedicated logging platform rather than printing them directly, reducing overhead while still capturing useful error information.