Errors & Debugging

Java checks your program twice. First javac, the compiler, reads the whole source file and refuses to produce bytecode if anything is wrong with the grammar or the types. Then the JVM runs the bytecode, and problems that only show up with real data — a null, an index past the end, a division by zero — are thrown as exceptions. The two look different, and knowing which one you have tells you where to look.

Anatomy of a javac error

Main.java:4: error: cannot find symbol
        System.out.println(totl);
                           ^
  symbol:   variable totl
  location: class Main
1 error
error: compilation failed

File and line (Main.java:4), the kind of error, the offending line with a caret under the exact token, extra detail lines, and the error count.

• Fix the first error first. One missing brace can produce ten follow-on errors; after fixing the first, recompile and many of the rest disappear.
• Trust the line, then look one line up. For a missing ; or ), javac often notices on the next token, so the real mistake is at the end of the previous line.
• Read the detail lines. symbol:, location:, required: and found: usually say exactly what is wrong.

Anatomy of a stack trace

Exception in thread "main" java.lang.NumberFormatException: For input string: "x"
	at java.base/java.lang.NumberFormatException.forInputString(Unknown Source)
	at java.base/java.lang.Integer.parseInt(Unknown Source)
	at java.base/java.lang.Integer.parseInt(Unknown Source)
	at Main.parse(Main.java:3)
	at Main.total(Main.java:8)
	at Main.main(Main.java:13)

The real trace from the program at the end of this lesson, without its try/catch. Line 1: the exception type and message. Then the call stack, newest call on top. The bottom frame is where the program started.

1. 1
   Read the first line

   The exception class and its message are often the whole answer: For input string: "x" means someone passed "x" to parseInt.

2. 2
   Skip the JDK frames

   Frames starting with java.base/ are inside the JDK. The JDK is almost never the bug.

3. 3
   Find the first frame in your code

   Main.parse(Main.java:3) is where your code made the call that failed. Open that line.

4. 4
   Read downward to see how you got there

   Each frame below is the caller: total line 8 called parse, and main line 13 called total. The bad value came in through that path.

5. 5
   If there is a "Caused by", jump to the last one

   Frameworks wrap exceptions. The deepest Caused by: section is the original failure, and its first frame in your code is where to start.

A stack trace is also an object you can inspect. This program catches the exception and prints only the frames that belong to Main, which is exactly the filter your eyes should apply:

public class Main {
    static int parse(String s) {
        return Integer.parseInt(s);
    }

    static int total(String[] items) {
        int t = 0;
        for (String s : items) t += parse(s);
        return t;
    }
    public static void main(String[] args) {
        try {
            total(new String[] {"4", "x"});
        } catch (NumberFormatException e) {
            System.out.println(e);
            for (StackTraceElement f : e.getStackTrace()) {
                if (f.getClassName().equals("Main")) {
                    System.out.println("  at " + f.getMethodName() + " line " + f.getLineNumber());
                }
            }
        }
    }
}

java.lang.NumberFormatException: For input string: "x"
  at parse line 3
  at total line 8
  at main line 13

These three are the errors you will see most in your first months. All of them are the compiler protecting you: it refuses to guess what you meant.

public class Main {
    public static void main(String[] args) {
        int total = 10;
        System.out.println(totl);
    }
}

Main.java:4: error: cannot find symbol
        System.out.println(totl);
                           ^
  symbol:   variable totl
  location: class Main
1 error
error: compilation failed

public class Main {
    public static void main(String[] args) {
        int total = 10;
        System.out.println(total);
    }
}

public class Main {
    public static void main(String[] args) {
        String input = "42";
        int n = input;
        System.out.println(n + 1);
    }
}

Main.java:4: error: incompatible types: String cannot be converted to int
        int n = input;
                ^
1 error
error: compilation failed

public class Main {
    public static void main(String[] args) {
        String input = "42";
        int n = Integer.parseInt(input);
        System.out.println(n + 1);
    }
}

public class Main {
    int add(int a, int b) {
        return a + b;
    }

    public static void main(String[] args) {
        System.out.println(add(2, 3));
    }
}

Main.java:7: error: non-static method add(int,int) cannot be referenced from a static context
        System.out.println(add(2, 3));
                           ^
1 error
error: compilation failed

public class Main {
    static int add(int a, int b) {
        return a + b;
    }

    public static void main(String[] args) {
        System.out.println(add(2, 3));
    }
}

javac also performs flow analysis: it follows every path through a method and proves that each variable is assigned before use, each non-void method returns, and no statement is dead. It also checks that every checked exception is handled. It does this without running anything, so it only reasons about the code's shape, not the values.

public class Main {
    static String grade(int score) {
        if (score >= 50) {
            return "pass";
        } else if (score < 50) {
            return "fail";
        }
    }

    public static void main(String[] args) {
        System.out.println(grade(70));
    }
}

Main.java:8: error: missing return statement
    }
    ^
1 error
error: compilation failed

public class Main {
    static String grade(int score) {
        if (score >= 50) {
            return "pass";
        } else {
            return "fail";
        }
    }

    public static void main(String[] args) {
        System.out.println(grade(70));
    }
}

public class Main {
    static int square(int x) {
        return x * x;
        System.out.println("squared " + x);
    }

    public static void main(String[] args) {
        System.out.println(square(4));
    }
}

Main.java:4: error: unreachable statement
        System.out.println("squared " + x);
        ^
1 error
error: compilation failed

public class Main {
    static int square(int x) {
        System.out.println("squaring " + x);
        return x * x;
    }

    public static void main(String[] args) {
        System.out.println(square(4));
    }
}

public class Main {
    public static void main(String[] args) {
        int bonus;
        int sales = 120;
        if (sales > 100) {
            bonus = 50;
        }
        System.out.println("Bonus: " + bonus);
    }
}

Main.java:8: error: variable bonus might not have been initialized
        System.out.println("Bonus: " + bonus);
                                       ^
1 error
error: compilation failed

public class Main {
    public static void main(String[] args) {
        int bonus = 0;
        int sales = 120;
        if (sales > 100) {
            bonus = 50;
        }
        System.out.println("Bonus: " + bonus);
    }
}

import java.nio.file.*;

public class Main {
    public static void main(String[] args) {
        String text = Files.readString(Path.of("notes.txt"));
        System.out.println(text);
    }
}

Main.java:5: error: unreported exception IOException; must be caught or declared to be thrown
        String text = Files.readString(Path.of("notes.txt"));
                                      ^
1 error
error: compilation failed

import java.io.IOException;
import java.nio.file.*;

public class Main {
    public static void main(String[] args) {
        try {
            String text = Files.readString(Path.of("notes.txt"));
            System.out.println(text);
        } catch (IOException e) {
            System.out.println("Could not read notes.txt: " + e.getMessage());
        }
    }
}

These programs compile cleanly and then fail while running, because a value was not what the code assumed. The fix is rarely a try/catch; it is usually validating the value or correcting the logic that produced it.

public class Main {
    record User(String name, String email) {}

    public static void main(String[] args) {
        User u = new User("Ada", null);
        System.out.println(u.email().toLowerCase());
    }
}

Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.toLowerCase()" because the return value of "Main$User.email()" is null
	at Main.main(Main.java:6)

public class Main {
    record User(String name, String email) {}

    public static void main(String[] args) {
        User u = new User("Ada", null);
        String email = u.email() == null ? "(no email)" : u.email().toLowerCase();
        System.out.println(email);
    }
}

public class Main {
    public static void main(String[] args) {
        int[] scores = {90, 75, 60};
        for (int i = 0; i <= scores.length; i++) {
            System.out.println(scores[i]);
        }
    }
}

90
75
60
Exception in thread "main" java.lang.ArrayIndexOutOfBoundsException: Index 3 out of bounds for length 3
	at Main.main(Main.java:5)

public class Main {
    public static void main(String[] args) {
        int[] scores = {90, 75, 60};
        for (int score : scores) {
            System.out.println(score);
        }
    }
}

public class Main {
    public static void main(String[] args) {
        String price = "19.99";
        int cents = Integer.parseInt(price);
        System.out.println(cents);
    }
}

Exception in thread "main" java.lang.NumberFormatException: For input string: "19.99"
	at java.base/java.lang.NumberFormatException.forInputString(Unknown Source)
	at java.base/java.lang.Integer.parseInt(Unknown Source)
	at java.base/java.lang.Integer.parseInt(Unknown Source)
	at Main.main(Main.java:4)

import java.math.BigDecimal;

public class Main {
    public static void main(String[] args) {
        String price = "19.99";
        BigDecimal amount = new BigDecimal(price.strip());
        int cents = amount.movePointRight(2).intValueExact();
        System.out.println(cents);
    }
}

public class Main {
    public static void main(String[] args) {
        Object value = "123";
        Integer n = (Integer) value;
        System.out.println(n + 1);
    }
}

Exception in thread "main" java.lang.ClassCastException: class java.lang.String cannot be cast to class java.lang.Integer (java.lang.String and java.lang.Integer are in module java.base of loader 'bootstrap')
	at Main.main(Main.java:4)

public class Main {
    public static void main(String[] args) {
        Object value = "123";
        if (value instanceof Integer n) {
            System.out.println(n + 1);
        } else if (value instanceof String s) {
            System.out.println(Integer.parseInt(s) + 1);
        }
    }
}

import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        Scanner in = new Scanner(System.in);
        System.out.print("Age: ");
        int age = in.nextInt();
        System.out.println("Next year you will be " + (age + 1));
    }
}

Age: Exception in thread "main" java.util.InputMismatchException
	at java.base/java.util.Scanner.throwFor(Unknown Source)
	at java.base/java.util.Scanner.next(Unknown Source)
	at java.base/java.util.Scanner.nextInt(Unknown Source)
	at java.base/java.util.Scanner.nextInt(Unknown Source)
	at Main.main(Main.java:7)

import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        Scanner in = new Scanner(System.in);
        System.out.print("Age: ");
        while (!in.hasNextInt()) {
            System.out.print("Please type a whole number: ");
            in.next();                       // discard the bad token
        }
        int age = in.nextInt();
        System.out.println("Next year you will be " + (age + 1));
    }
}

Reading the error tells you where the program failed. When it did not crash but gave the wrong answer, you need to see what it was thinking. Java has three tools for that, in order of how often you will use them.

1. The IDE debugger

1. 1
   Set a breakpoint

   Click the gutter next to a line number. Run with Debug (the bug icon) instead of Run; the program pauses when it reaches that line.

2. 2
   Inspect

   The Variables panel shows every local and field right now. Hover over any expression, or add it to Watches to track it across steps.

3. 3
   Step

   Step Over (F8 in IntelliJ) runs the current line. Step Into (F7) enters the method being called. Step Out finishes the current method. Resume runs to the next breakpoint.

4. 4
   Use conditional breakpoints

   Right-click a breakpoint and add a condition such as i == 999 or name == null to stop only on the iteration that matters.

5. 5
   Break on exceptions

   An exception breakpoint for NullPointerException pauses at the exact moment it is thrown, with every variable still on screen.

Without an IDE, the JDK ships jdb, a command-line debugger, and every IDE can attach to a JVM started with the debug agent — which is how you debug a server running in Docker.

# start a program so a debugger can attach on port 5005
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar

# command-line debugger (breakpoint on a method, then run)
jdb -classpath . Main
> stop in Main.average
> run

# a hung program: print every thread and any deadlock
jcmd <pid> Thread.print

2. Print debugging, done properly

A few well-placed prints are a legitimate tool, especially for loops. Print the loop variable and the state together, and let records do the formatting for you. The output below exposes a bug at a glance: the running maximum starts at 0, so an all-negative input reports 0.

public class Main {
    record Step(int i, int value, int max) {}

    public static void main(String[] args) {
        int[] temps = {-7, -3, -12};
        int max = 0;                          // bug: should start at temps[0]
        for (int i = 0; i < temps.length; i++) {
            if (temps[i] > max) max = temps[i];
            System.out.println(new Step(i, temps[i], max));
        }
        System.out.println("max = " + max);
    }
}

Step[i=0, value=-7, max=0]
Step[i=1, value=-3, max=0]
Step[i=2, value=-12, max=0]
max = 0

3. Logging for code that runs without you

Prints are deleted before commit. Logging stays: it has levels (so debug detail can be switched off in production), timestamps, the thread name, and goes to files or a log platform. The JDK has java.util.logging and System.Logger; real projects almost always use SLF4J with Logback or Log4j 2.

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class OrderService {
    private static final Logger log = LoggerFactory.getLogger(OrderService.class);

    void place(Order order) {
        log.debug("placing order {} with {} items", order.id(), order.items().size());
        try {
            payments.charge(order);
            log.info("order {} placed", order.id());
        } catch (PaymentException e) {
            log.error("payment failed for order {}", order.id(), e);   // pass e LAST: the stack trace is logged
            throw e;
        }
    }
}

Use {} placeholders instead of string concatenation (the message is only built if that level is enabled), and pass the exception as the final argument so its stack trace is not lost.

jshell: answer "what does this do?" in five seconds

jshell (in every JDK since 9) is a REPL: type an expression, see the value. Use it to check an API before writing a program around it.

$ jshell
jshell> Integer.parseInt(" 42".strip())
$1 ==> 42

jshell> "a,b,,c".split(",")
$2 ==> String[4] { "a", "b", "", "c" }

jshell> 7 / 2
$3 ==> 3

jshell> 7 / 2.0
$4 ==> 3.5

jshell> /exit

Compile error

A problem javac finds before anything runs; no bytecode is produced.

Runtime exception

An unchecked exception thrown while the program runs (subclass of RuntimeException).

Checked exception

An exception the compiler forces you to catch or declare, such as IOException.

Stack trace

The exception type, message and the chain of method calls (frames) that led to it, newest first.

Caused by

A wrapped original exception inside a stack trace; the deepest one is the root cause.

Helpful NPE

The Java 14+ NullPointerException message that names the exact null expression.

Breakpoint

A line where the debugger pauses the program so you can inspect variables.

jshell

The JDK's interactive REPL for trying Java expressions.