Why Dubbo Wraps Custom Exceptions into RuntimeException and How to Fix It

This article presents a real interview scenario where a Dubbo consumer fails to catch a custom HelloException thrown by the provider, because Dubbo wraps the exception into a generic RuntimeException. The author reproduces the problem with a minimal Dubbo demo, showing the provider, service interface, and consumer code.

public class HelloException extends RuntimeException { }

public interface DemoService { String sayHello(String name); }

public class DemoServiceImpl implements DemoService {
    public String sayHello(String name) {
        throw new HelloException("公众号:肥朝");
    }
}

public class DemoAction {
    private DemoService demoService;
    public void setDemoService(DemoService demoService) { this.demoService = demoService; }
    public void start() throws Exception {
        try {
            String hello = demoService.sayHello("公众号:肥朝");
        } catch (HelloException e) {
            System.out.println("这里捕获helloException异常");
        }
    }
}

The author then inspects Dubbo's ExceptionFilter source, which decides whether to propagate the original exception or wrap it. The filter checks five conditions:

If the exception is a checked exception, it is re‑thrown directly.

If the method signature declares the exception, it is re‑thrown.

If the exception class and the service interface are in the same JAR, it is re‑thrown.

If the exception belongs to the JDK (starts with java. or javax.), it is re‑thrown.

If the exception is a Dubbo‑specific exception such as RpcException, it is re‑thrown.

When none of the above conditions are satisfied, Dubbo wraps the exception into a RuntimeException so that it can be serialized across the network. Because HelloException is a custom runtime exception defined in common.jar (different from the API JAR), it fails all checks and is therefore wrapped, making the consumer's catch (HelloException) block ineffective.

The article explains why Dubbo makes this design choice: to avoid serialization failures when a provider throws an exception that the consumer cannot see on its classpath. By wrapping it into a standard runtime exception, the exception can always be transferred.

To solve the problem, the author suggests several practical approaches, such as declaring the custom exception in the service interface, placing the exception class in the shared API JAR, or using a checked exception that the consumer knows about.

Finally, the author shares interview tips and emphasizes that understanding the underlying source code and the rationale behind Dubbo's design can turn a tricky interview question into a showcase of deep technical competence.