Java: How to create and throw a custom exception

Java exceptions FAQ: How do I create a custom exception in Java?

Java “custom exception” solution

The solution is to:

1. Create a custom exception class in Java
2. Throw the custom Java exception
3. In other code, catch the custom exception, and
4. Look at the output from our custom exception when we print a stack trace

I demonstrate this in the following example.

A Java custom exception class

To get started, this is pretty much the simplest possible Java custom exception class. As shown, to create a custom exception class, extend the Java Exception class and create a constructor:

/**
 * A Java “custom exception” class.
 * https://alvinalexander.com
 */
class AlsCustomException extends Exception
{
    public AlsCustomException(String message)
    {
        super(message);
    }
}

As you'll see later there are more Exception class constructors you can override, but this is a good start for a simple example.

A method to throw a custom Java exception

To demonstrate how to throw our exception, here's a small example class with a method named getBar that will throw our custom exception (AlsCustomException) if the method is given the value of zero as a parameter (sorry, not much imagination there, just trying to keep it simple):

/**
 * Our test class to demonstrate our custom exception.
 */
class Foo
{
  public String getBar(int i)
  throws AlsCustomException
  {
    if (i == 0)
    {
      // throw our custom exception
      throw new AlsCustomException("Anything but zero ...");
    }
    else
    {
      return "Thanks";
    }
  }
}

As you can see, all you need to do to throw your custom exception is (1) create a new instance of the exception (new AlsCustomException("Anything but zero ...")), and then (2) throw that exception with the throw keyword.

A driver class to test (throw) the custom Java exception

With those two pieces in place, we'll create a "driver" class with a main method to test our custom Java exception. In our main method, we'll create a new instance of our Foo class, then call the getBar method with the value of zero, which makes that method throw our custom Java exception:

/**
 * A class to test (throw) the custom exception we've created.
 * @author alvin alexander, devdaily.com
 *
 */
public class JavaCustomExceptionExample
{
  public static void main(String[] args)
  {
    // create a new foo
    Foo foo = new Foo();
    
    try
    {
      // intentionally throw our custom exception by
      // calling getBar with a zero
      String bar = foo.getBar(0);
    }
    catch (AlsCustomException e)
    {
      // print the stack trace
      e.printStackTrace();
    }
  }
}

Output from a driver class

With all those pieces in place, when we compile and run our Java source code, we get the following output when we print our stack trace:

AlsCustomException: Anything but zero ...
	at Foo.getBar(JavaCustomExceptionExample.java:37)
	at JavaCustomExceptionExample.main(JavaCustomExceptionExample.java:18)

As you can see, our custom exception output looks a lot like the output from any other Java exception that you've seen. The name of our exception is shown on the first line of the stack trace, followed by our error message.

I hope this is all pretty straightforward. As a friend of mine used to say, "this isn't too hard ... once you know how to do it." :)

Java Exception class constructors

For more information on the topic of Java exceptions, check out the Java Exception class javadoc. As you'll see in that javadoc, the Exception class has the following constructors. We only overloaded one of these constructors, but in your own custom exception class you may want to override several of them:

1. Exception()
2. Exception(String message)
3. Exception(String message, Throwable cause)
4. Exception(Throwable cause)

Download the custom exception source code

If you're interested in running your own Java custom exception tests, feel free to download our Java custom exception example source code. All of the Java source code shown above is included in this one file.