@SneakyThrows

Overview

@SneakyThrows can be used to sneakily throw checked exceptions without actually declaring this in your method's throws clause. This somewhat contentious ability should be used carefully, of course. The code generated by lombok will not ignore, wrap, replace, or otherwise modify the thrown checked exception; it simply fakes out the compiler. On the JVM (class file) level, all exceptions, checked or not, can be thrown regardless of the throws clause of your methods, which is why this works.

Common use cases for when you want to opt out of the checked exception mechanism center around 2 situations:

  • A needlessly strict interface, such as Runnable - whatever exception propagates out of your run() method, checked or not, it will be passed to the Thread's unhandled exception handler. Catching a checked exception and wrapping it in some sort of RuntimeException is only obscuring the real cause of the issue.
  • An 'impossible' exception. For example, new String(someByteArray, "UTF-8"); declares that it can throw an UnsupportedEncodingException but according to the JVM specification, UTF-8 must always be available. An UnsupportedEncodingException here is about as likely as a ClassNotFoundError when you use a String object, and you don't catch those either!

Be aware that it is impossible to catch sneakily thrown checked types directly, as javac will not let you write a catch block for an exception type that no method call in the try body declares as thrown. This problem is not relevant in either of the use cases listed above, so let this serve as a warning that you should not use the @SneakyThrows mechanism without some deliberation!

You can pass any number of exceptions to the @SneakyThrows annotation. If you pass no exceptions, you may throw any exception sneakily.

NOTE: with lombok versions older than 0.10, unlike other lombok transformations, you need to put lombok.jar on your classpath when you run your program.

With Lombok

01 import lombok.SneakyThrows;
02 
03 public class SneakyThrowsExample implements Runnable {
04   @SneakyThrows(UnsupportedEncodingException.class)
05   public String utf8ToString(byte[] bytes) {
06     return new String(bytes, "UTF-8");
07   }
08   
09   @SneakyThrows
10   public void run() {
11     throw new Throwable();
12   }
13 }

Vanilla Java

01 import lombok.Lombok;
02 
03 public class SneakyThrowsExample implements Runnable {
04   public String utf8ToString(byte[] bytes) {
05     try {
06       return new String(bytes, "UTF-8");
07     catch (UnsupportedEncodingException e) {
08       throw Lombok.sneakyThrow(e);
09     }
10   }
11   
12   public void run() {
13     try {
14       throw new Throwable();
15     catch (Throwable t) {
16       throw Lombok.sneakyThrow(t);
17     }
18   }
19 }

Small print

Because @SneakyThrows is an implementation detail and not part of your method signature, it is an error if you try to declare a checked exception as sneakily thrown when you don't call any methods that throw this exception. (Doing so is perfectly legal for throws statements to accommodate subclasses). Similarly, @SneakyThrows does not inherit.

For the nay-sayers in the crowd: Out of the box, Eclipse will offer a 'quick-fix' for uncaught exceptions that wraps the offending statement in a try/catch block with just e.printStackTrace() in the catch block. This is so spectacularly non-productive compared to just sneakily throwing the exception onwards, that Roel and Reinier feel more than justified in claiming that the checked exception system is far from perfect, and thus an opt-out mechanism is warranted.

If you put @SneakyThrows on a constructor, any call to a sibling or super constructor is excluded from the @SneakyThrows treatment. This is a java restriction we cannot work around: Calls to sibling/super constructors MUST be the first statement in the constructor; they cannot be placed inside try/catch blocks.

@SneakyThrows on an empty method, or a constructor that is empty or only has a call to a sibling / super constructor results in no try/catch block and a warning.