Expand Authors Top

If you have a few years of experience in the Java ecosystem and you’d like to share that with the community, have a look at our Contribution Guidelines.

Expanded Audience – Frontegg – Security (partner)
announcement - icon User management is very complex, when implemented properly. No surprise here.

Not having to roll all of that out manually, but instead integrating a mature, fully-fledged solution - yeah, that makes a lot of sense.
That's basically what Frontegg is - User Management for your application. It's focused on making your app scalable, secure and enjoyable for your users.
From signup to authentication, it supports simple scenarios all the way to complex and custom application logic.

Have a look:

>> Elegant User Management, Tailor-made for B2B SaaS

November Discount Launch 2022 – Top
We’re finally running a Black Friday launch. All Courses are 30% off until tomorrow:


NPI – Lightrun – Spring (partner)

We rely on other people’s code in our own work. Every day. It might be the language you’re writing in, the framework you’re building on, or some esoteric piece of software that does one thing so well you never found the need to implement it yourself.

The problem is, of course, when things fall apart in production - debugging the implementation of a 3rd party library you have no intimate knowledge of is, to say the least, tricky. It’s difficult to understand what talks to what and, specifically, which part of the underlying library is at fault.

Lightrun is a new kind of debugger.

It's one geared specifically towards real-life production environments. Using Lightrun, you can drill down into running applications, including 3rd party dependencies, with real-time logs, snapshots, and metrics. No hotfixes, redeployments, or restarts required.

Learn more in this quick, 5-minute Lightrun tutorial:

>> The Essential List of Spring Boot Annotations and Their Use Cases

1. Overview

In this tutorial, we're going to see what causes Java to throw an instance of the UndeclaredThrowableException exception.

First, we'll start with a bit of theory. Then, we'll try to better understand the nature of this exception with two real-world examples.

2. The UndeclaredThrowableException

Theoretically speaking, Java will throw an instance of UndeclaredThrowableException when we try to throw an undeclared checked exception. That is, we didn't declare the checked exception in the throws clause but we throw that exception in the method body.

One might argue that this is impossible as the Java compiler prevents this with a compilation error. For instance, if we try to compile:

public void undeclared() {
    throw new IOException();

The Java compiler fails with the message:

java: unreported exception java.io.IOException; must be caught or declared to be thrown

Even though throwing undeclared checked exceptions may not happen at compile-time, it's still a possibility at runtime. For example, let's consider a runtime proxy intercepting a method that doesn't throw any exceptions:

public void save(Object data) {
    // omitted

If the proxy itself throws a checked exception, from the caller's perspective, the save method throws that checked exception. The caller probably doesn't know anything about that proxy and will blame the save for this exception.

In such circumstances, Java will wrap the actual checked exception inside an UndeclaredThrowableException and throw the UndeclaredThrowableException instead. It's worth mentioning that the UndeclaredThrowableException itself is an unchecked exception.

Now that we know enough about the theory, let's see a few real-world examples.

3. Java Dynamic Proxy

As our first example, let's create a runtime proxy for java.util.List interface and intercept its method calls. First, we should implement the InvocationHandler interface and put the extra logic there:

public class ExceptionalInvocationHandler implements InvocationHandler {

    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        if ("size".equals(method.getName())) {
            throw new SomeCheckedException("Always fails");
        throw new RuntimeException();

public class SomeCheckedException extends Exception {

    public SomeCheckedException(String message) {

This proxy throws a checked exception if the proxied method is size. Otherwise, it'll throw an unchecked exception.

Let's see how Java handles both situations. First, we'll call the List.size() method:

ClassLoader classLoader = getClass().getClassLoader();
InvocationHandler invocationHandler = new ExceptionalInvocationHandler();
List<String> proxy = (List<String>) Proxy.newProxyInstance(classLoader, 
  new Class[] { List.class }, invocationHandler);


As shown above, we create a proxy for the List interface and call the size method on it. The proxy, in turn, intercepts the call and throws a checked exception. Then, Java wraps this checked exception inside an instance of UndeclaredThrowableException. This is happening because we somehow throw a checked exception without declaring it in the method declaration.

If we call any other method on the List interface:


Since the proxy throws an unchecked exception, Java lets the exception to propagate as-is.

4. Spring Aspect

The same thing happens when we throw a checked exception in a Spring Aspect while the advised methods didn't declare them. Let's start with an annotation:

public @interface ThrowUndeclared {}

Now we're going to advise all methods annotated with this annotation:

public class UndeclaredAspect {

    public Object advise(ProceedingJoinPoint pjp, ThrowUndeclared undeclared) throws Throwable {
        throw new SomeCheckedException("AOP Checked Exception");

Basically, this advice will make all annotated methods to throw a checked exception, even if they didn't declare such an exception. Now, let's create a service:

public class UndeclaredService {

    public void doSomething() {}

If we call the annotated method, Java will throw an instance of UndeclaredThrowableException exception:

@SpringBootTest(classes = UndeclaredApplication.class)
public class UndeclaredThrowableExceptionIntegrationTest {

    @Autowired private UndeclaredService service;

    public void givenAnAspect_whenCallingAdvisedMethod_thenShouldWrapTheException() {

As shown above, Java encapsulates the actual exception as a cause and throws the UndeclaredThrowableException exception instead.

5. Conclusion

In this tutorial, we saw what causes Java to throw an instance of the UndeclaredThrowableException exception.

As usual, all the examples are available over on GitHub.

November Discount Launch 2022 – Bottom
We’re finally running a Black Friday launch. All Courses are 30% off until tomorrow:


Generic footer banner
Comments are closed on this article!