This is intended as a reference guide as well as a tutorial on how to get started with debugging Java programs. For beginners, we assume you have some basic knowledge of Java syntax and the JVM and memory model, and we recommend you start from the beginning. Here is a handy list of links in the document for quick-reference:

• Throwables
  • The Java Call Stack
• Stack Traces
• Basic Debugging via println()
• Checked Exceptions
  • IOException
• Unchecked Exceptions
  • NullPointerException
  • IndexOutOfBoundsException
  • ClassCastException
  • IllegalArgumentException
• Runtime Errors
  • NoClassDefFoundError
  • OutOfMemoryError
  • StackOverflowError

Throwables and Reading Stack Traces

• Java provides us with two methods of identifying errors in programs: Exceptions and Errors
  • Exceptions are meant to indicate "exceptional conditions" - that is, a set of cirucmstances has occurred in the program that might prevent the program from continuing execution past that point. However, depending on the type of Exception that is raised, you may be able to recover from the circumstances - either by ignoring it entirely, or by taking action to fix the "exceptional condition." This constitutes most of the errors you will run in to.
  • Errors are not nearly as nice. When the Java Virtual Machine throws an Error, it's serious business. These are also "exceptional conditions" but the Java API goes on and indicates that they are most often results of "abnormal conditions." Errors are things that "reasonable" applications should not try to recover from. (What is "reasonable" you ask? If you are writing a program that needs to recover from an Error, you will definitely know about it. For our purposes, we will label recovering from errors as a Bad Idea)
• Both Exceptions and Errors are subclasses of Throwable
  • A Throwable object is, quite simply, an object than can be thrown.
    • Wait, wait a second, that definition does me no good.
  • A second try: A Throwable object is an object that, when used with the throw keyword, will stop the method's execution and attempt to propagate upwards through th call stack.
    • HUH?!?!
• Aside: the Java Call Stack (short version)
  • Take the following code for example:

    public int getMagicNumber() {
    
         int average = computeAverage(num1, num2);
         return average * 42;
    }
    
    
    public int computeAverage(int first, int second) {
    
         int average = (first + second) / 2;
    
         return average;
    
    }
    
    

    Say you call the getMagicNumber() method. It will then call the computeAverage() method itself. When the computeAverage() method completes though, it has to know where to jump back to - in our case, the first line of the getMagicNumber() method. Java does this by keeping track of every method on a call stack - that is, every method that gets called, is "stacked" on top of the method it is called from. In our example, the call stack when computeAverage() is running would look something like this:
    
    
    
    as opposed to AFTER computeAverage() completes, it would just be:
    
    
    
  • Each layer on the stack (sometimes called an activation record, or stack frame) contains: the method called, along with the location of the call. So, our 2-layer stack would record the fact that computeAverage() was called from the first line of getMagicNumber() (and indeed, wherever getMagicNumber() itself was called from...)
    
• Whew. Okay. So, let's try that again, using our example:
  • If a Throwable object were thrown in the middle of computeAverage(), it would record the line number it was thrown at, as well as the method (it basically copies the "stack layer") and pops back up, into getMagicNumber(). It will then copy the "stack layer" for getMagicNumber() and continue popping upwards in the call hierarchy until it a) reaches the top, or b) you stop it.
• So what?
  • The point of understanding how a Throwable works is because it is essential to deciphering the error messages Java gives you. Take the following exception for example:
    

    java.sql.SQLException: Can not issue NULL query.
    	at com.mysql.jdbc.Statement.checkNullOrEmptyQuery(Statement.java:1471)
    	at com.mysql.jdbc.Statement.executeUpdate(Statement.java:1231)
    	at com.mysql.jdbc.Statement.executeUpdate(Statement.java:1335)
    	at DatabaseConnection.execWithGetKeys(DatabaseConnection.java:90)
    	at XMLInserter.commitArticleData(XMLInserter.java:99)
    	at XMLInserter$XMLHandler.endElement(XMLInserter.java:168)
    	at com.icl.saxon.aelfred.SAXDriver.endElement(SAXDriver.java:792)
    	at com.icl.saxon.aelfred.XmlParser.parseETag(XmlParser.java:1133)
    	at com.icl.saxon.aelfred.XmlParser.parseContent(XmlParser.java:1217)
    	at com.icl.saxon.aelfred.XmlParser.parseElement(XmlParser.java:1037)
    	at com.icl.saxon.aelfred.XmlParser.parseContent(XmlParser.java:1222)
    	at com.icl.saxon.aelfred.XmlParser.parseElement(XmlParser.java:1037)
    	at com.icl.saxon.aelfred.XmlParser.parseDocument(XmlParser.java:510)
    	at com.icl.saxon.aelfred.XmlParser.doParse(XmlParser.java:163)
    	at com.icl.saxon.aelfred.SAXDriver.parse(SAXDriver.java:320)
    	at javax.xml.parsers.SAXParser.parse(Unknown Source)
    	at javax.xml.parsers.SAXParser.parse(Unknown Source)
    	at XMLInserter.main(XMLInserter.java:45)
    		

    The above exception probably has very little meaning to you (if you are curious, it is taken from a piece of code that inserts XML into a database), and that's okay. What we do want to show you though is how to extract the information you need to begin pinpointing the "exceptional condition."
  • Each line of this exception report, or stack trace (except the first line - we will deal with that in the next heading) gives us three vital pieces of information:
    • The method (and respective class) name
    • The file name
    • The line number
  • Excellent! Java tells me exactly where to look! That's easy!
    • It's not always that easy.
  • USUALLY, the first place you ought to look when you receive a stack trace from Java is the location specified at the first line.
    • This is not always the case. Here are two circumstances when you might need to look at the next line (i.e. the next layer in your stack):
      • You looked at the location it specifies and it doesn't look like it has any incorrect code
      • You don't have the source code. This is the case in the sample stack trace above (the com.mysql.jdbc.Statement is in a compiled library - the entire Java API is itself a compiled library). In most cases, it is safe to assume that compiled libraries or other supplied code are tested and correct, and therefore the problem must lie in your code somewhere upstream (i.e. you may be using the supplied code incorrectly).
    • When you do look at the next location specified in the stack frame, you are looking for:
      • Glaring omissions of circumstances you may not want to occur
      • Method inputs - sometimes bad input can cause errors down the line in code you never even wrote!
      • More about what to look for in the next section

Common Exceptions and Errors

There are three distinct classes of error messages Java gives you: checked exceptions, unchecked exceptions, and error messages (generally checked and unchecked fall under the "Exceptions" vs. "Errors" category and is further refined, but since they provide different kinds of information, and involve different debugging styles, we'll treat them separately).

• Checked Exceptions
  • These are Exceptions that are explicitly defined in the API, or by your own code. The semantics of when these exceptions occur usually are mentioned in the API (or, if your own code produces them, you should know when and under what circumstances). These are the most common recoverable errors.
  • In order to debug these exceptions, you should check the API you are using, as well as the first line of the stack trace, which usually prints informative output.
  • IOException
    • When it occurs: Many File/URL I/O operations can potentially throw this. Common reasons can include: file not found, you've read past the end of the stream, bad URL, etc.
    • How to debug it: Check your file system, read the API, make sure your code doesn't enter into any of the circumstances when the API specifies the exception will be thrown
  • Follow a similar debugging procedure for other checked exceptions
• Unchecked Exceptions
  • These are the big ones you need to worry about. All of these exceptions extend RuntimeException, and do not need to be declared by the method throwing them. This means that unless you have a try/catch block somewhere in your call hierarchy, these exceptions will STOP YOUR PROGRAM DEAD. This is why it is so imperative that proper caution be taken to avoid these exceptions, and that you know how to fix them when they occur.
  • NullPointerException
    • When it occurs: This is by far the most common exception thrown in most Java programs. It is thrown whenever an object variable/reference is null, but you still try to access one of its methods or fields. A simple example:
      

      String str = null;
      System.out.println(str.length());

      This code will throw a NPE (for short) on the second line. Here is a more complex example:
      

      LinkedList<Request> queue = new LinkedList<Request>();
      Request req = new Request();
      req.prepare();
      req.setMessageBuffer(null); //assume setMessage takes a StringBuffer object
      String message = queue.poll().getMessageBuffer().toString();

      This example is a bit more complicated. Let's see why.

    • How to debug it: Assuming we had actually created a Request class, and put the above code somewhere and tried to compile and run it, we might get a stack trace something like the following:
      

      NullPointerException: 
        at SomeClass.someMethod(SomeClass.java:16)
        at SomeClass.someParentMethod(SomeClass.java:45)
        at SomeClass.main(SomeClass.java:90)

      For this contrived example, assume line 16 corresponds to:
      

      String message = queue.poll().getMessageBuffer().toString();

      A NullPointerException usually will not give you any descriptive message, as most other Exceptions do. Luckily, the fact that it is an NPE, along with the location, is information enough for us.

      • First, we look at the line number corresponding to the top element of the stack trace. We find our line (the above one) and stare at it and ask ourselves, "what could be null?"
      • Aha! Clearly, the problem is the getMessageBuffer() method! The line right beforehand sets it to null (and we assume these aren't any special getters/setters)! Bingo!
      • So, to fix it, I'll just give it a new StringBuffer() and it will leave me alone. Simple, right?
        • No. We still get the same exception:
          

          NullPointerException: 
            at SomeClass.someMethod(SomeClass.java:16)
            at SomeClass.someParentMethod(SomeClass.java:45)
            at SomeClass.main(SomeClass.java:90)

      • What to do?

A BRIEF INTERLUDE - DEBUGGING BY println()

When you are running a Java program, as far as we know, we cannot stop it. It either runs to completion or till an error/exception kills it. But what if we need to find out information while the program is running? What if we want to know the contents of a variable at any particular time?

The answer that may already have occurred to you is to use System.out.println(). You can print out the contents or toString() of any variable (this is why it's useful to override toString()). When the program reaches your statement, it will, quite simply, print out what you ask it to. It is generally useful to also print out some sort of label along with your variable so you know what's being printed and don't get confused. If you're printing out the index of a for loop, you may want something like:

System.out.println("i = "+i);

If your program is dying somewhere though and you don't even know where to look or what variables to print out, you can still use the println() debugging method. Take one line, such as:

System.out.println("I'm still alive!");

and place it smack before the return statement or end of the method/piece of code you suspect is causing the error. Run your program. If the words "I'm still alive!" are printed out, you know that your program executes till that point, and you may be looking at the wrong method (you may want to repeat the process one level higher in the call stack). If they aren't printed out, you know the program dies somewhere between the "start" of the program and the "end" of that method.

Now, we need to narrow our scope of where the error could be. Cut and paste the println() statement and put it in another place: right in the middle of the method. Run your program again.

If "I'm still alive" is printed out, you know that the first half of your method runs well, and the problem probably lies in the second half. Repeat the method by placing the println statement in the middle of the second half. If "I'm still alive" is not printed out, the problem lies in the first half. Repeat on the first half. This is called the divide-and-conquer approach, and is a great basic way to start debugging programs (and is how most programmers start out debugging).

• Now we've set that straight, it seems simple. Break up the chained method calls and print out their result. Eventually we may end up with something like this:
  

  Request currentRequest = queue.poll();
  System.out.println("Request is "+currentRequest);
  StringBuffer buf = currentRequest.getMessageBuffer();
  System.out.println("Buffer is "+buf);
  String message = buf.toString();

  When we run this excerpt, the output would probably look something like this:
  

  Request is null
  NullPointerException: 
    at SomeClass.someMethod(SomeClass.java:17)
    at SomeClass.someParentMethod(SomeClass.java:45)
    at SomeClass.main(SomeClass.java:90)
              

  And so, it seems we've located the problem, thanks to handy-dandy println() debugging!

• How to prevent it: When writing code, always be aware of what could potentially be null. If there is something that could be null, enclose any code that uses its members (fields/methods) in an if statement that checks if the reference is null.
• IndexOutOfBoundsException
• When it occurs: This comes in three flavors: IndexOutOfBoundsException (IOOBE), and its two subclasses: ArrayIndexOutOfBoundsException (AIOOBE) and StringIndexOutOfBoundsException (SIOOBE). These occur when you try to access a list, array, String, or other indexed collection with an index that isn't within the valid set of ranges.
• How to debug it: The rest of the runtime exceptions can usually be debugged in a method similar to the ones described above. We'll just point out things to look for. With IOOBEs, you are generally looking for some access to an index that is either negative, or greater than the size of the indexed object (array, String, whatever) - the message printed along with the IOOBE tells you the actual value that it tried to use as the index. A useful thing is to print out the size of the indexed object before the error occurs. Many times, these errors have an underlying problem where the code doesn't take into account the size of the object at all times.
• How to prevent it: Always use if statements to verify that the size of the object is as you expect. When writing code, consider all possible accesses to the object that could modify the size unexpectedly.
• ClassCastException
  • When it occurs: This error always occurs when you try to cast an object to a type it cannot be cast to. This sounds simple, but can be tricky. It occurs more often with down-casting, rather than up-casting (it is usually easier to keep track of a class's parents, rather than all its subclasses). It primarily occurs in two situations:
    • Explicit casts, e.g.:
      List list = new ArrayList();
      ArrayList aList = (ArrayList) list;
    • When using generics, specifically with collections, e.g.:
      List<String> list = new ArrayList<String>();
      list.add("foo"); list.add("bar");
      String first = list.get(0);
      • This doesn't look like a cast at first glance, but under the hood the compiler actually manually inserts an explicit cast to String for you.
  • How to debug it: This can sometimes be tricky. Here's a good example. Say you want to override an object's equals() method, which takes an Object. Say you are writing the equals() method on a class called StringWrapper, that simply wraps a String object, and has a getWrappedString() method. In order to determine equality with another StringWrapper, you just want to compare the wrapped strings, so you write something like this:
    

    public boolean equals(Object other) {
    
         return this.getWrappedString().equals(((StringWrapper)other).getWrappedString());
    
    }

    Looks simple, and in fact it works correctly. Except, it works correctly if it's always passed StringWrapper objects - which may be the case. However, what if we do the following:
    

    List myList = new ArrayList();
    StringWrapper hello = new StringWrapper("hi");
    StringWrapper goodbye = new StringWrapper("bye");
    //some other code here...
    myList.add(hello); 
    //even more code...
    myList.add("goodbye");
    for(Object object : myList) {
         if(hello.equals(object) || goodbye.equals(object)) 
              printGreeting(object);
    }

    Looks fine (I mean, equals() takes an Object!), but we get something like:
    

    ClassCastException: java.lang.String
      at StringWrapper.equals(StringWrapper.java:7)
      at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
      at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
      at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
      at java.lang.reflect.Method.invoke(Unknown Source)
    

    Fortunately, the ClassCastException message tells us this: "there is an object, whose lowest-level class is that of java.lang.String. You just tried to cast it to something it cannot be cast to. Shame on you." Unfortunately, it does not tell us what you tried to cast it to, nor what variable contains the offending java.lang.String.
    
    Luckily, casts are easy to spot in code, and there generally too aren't many of them on one line. If there are, and you have no idea what class a particular object is (a highly feasible situation, especially once you get into more complicated APIs), you can use your trusty println() debugging method and do something like:
    System.out.println(myVar.getClass());
    If you need to, feel free to break up multiple methods in one line into separate variables on separate lines to make this printout easier. The bonus you get out of this is you see which method call produces the unexpected type.
  • How to prevent it: In order to prevent bad casting, there is a very simple, easy way to get around numerous problems. If you are ever in a situation where you think a cast can possibly have the slightest chance of going wrong, simply wrap your cast and associated code in an if statement that uses the instanceof operator. A more appropriate version of the above equals method would be:
    

    public boolean equals(Object other) {
    	if(other instanceof StringWrapper)
    		return this.getWrappedString().equals(((StringWrapper)other).getWrappedString());
    	else
    		return false;
    }

    When in doubt with casting, use instanceof.
• IllegalArgumentException
  • When it occurs: This is often just a fallback exception that methods will often throw if they get unexpected arguments. Unlike the above three, which are usually thrown by the JVM itself, the IllegalArgumentException is usually thrown by actual method code (the APIs count as method code).
    • There are also many subclasses, one of the most common being the NumberFormatException which is usually thrown when one of the primitive wrapper classes has trouble parsing a String into a number.
  • How to debug it: Isolate the problematic method call that issues the exception. Read the documentation on that method very carefully. It will usually tell you when it will throw an IllegalArgumentException. Adjust your code with if statements and logic changes to ensure that those situation(s) never happen.
  • How to prevent it: As mentioned above, always be aware of the documentation and make appropriate safeguards in your code to avoid bad situations.
• Runtime Errors
  • As mentioned above, these things are serious business. Most of them are strange and can result from corrupted class files, and you shouldn't hesitate to ask for help on them. That said though, there are a couple of common ones that on the surface seem like insurmountable problems, but can often indicate that a simpler problem underlies them. Here are three of the most common ones:
  • NoClassDefFoundError
    • When it occurs: As the name suggests, this occurs when the JVM cannot find the class file you are trying to access. Some common situations that could lead to this:
      • You forgot to compile a file. Oops.
      • You compiled, and some classes compiled okay, and some didn't. The ones that compiled okay might try to indirectly access the ones that didn't compile sometimes.
        • This can also happen if you have a class that relies on some other class contained in a JAR file, and the JVM cannot find the specified JAR file (it wasn't in the classpath) or can't find the class within the file
      • You didn't specify the correct package name on the command line.
      • Messy/incorrect package or directory structure.
    • How to debug it: The NoClassDefFoundError will always give you a message of what class it couldn't find. From there, it's up to you to look into why that file isn't compiled. Or, in the case of incorrect package name, the JVM will usually even suggest to you what the correct package name is!
    • How to prevent it: Always make sure your files fully compile without errors and preferably without warnings. Be aware of package and directory structures.
  • OutOfMemoryError and StackOverflowError
    • When they occur: These two are really two flavors of the same basic type of error: the JVM has run out of memory. More specifically:
      • OutOfMemoryError occurs when there is no more HEAP MEMORY available to allocate a new object.
      • StackOverflowError occurs when there is no more STACK MEMORY available to allocate a new variable on the stack.
      At first, these can be very intimidating and may have you stumped as to how to proceed. Practically though, these errors are often caused by some of the following common situations:
      • Memory leaks
      • Endless loops (usually coupled with memory leaks; a plain endless loop will probably just hang)
      • Infinite recursion
    • How to debug them: These are actually some of the trickiest errors to debug. In most cases though, they will probably result from infinite recursion - an endless sequence of a method calling itself with no stop point. These errors will not always consistently give you useful information (though they should sometimes give a location of where it was last trying to allocate an object).
      
      If you have written recursive methods, you should know where they are and examine them very carefully. Make sure they are theoretically correct on-paper, and make sure they have the correct base case implemented.
      
      If for some reason recursion is NOT the issue, then the problem becomes more significant. If you actually do just need a large amount of memory legitimately, you can increase the heap/stack size in the java commandline with the -Xmx parameter. If that still doesn't help though, you are most likely the victim of a memory leak. There are tools, called profilers, that help you identify memory leaks, but they are an advanced topic and we will not go into them here.