Finding help in error messages and the standard library docs

Understanding Finding help in error messages and the standard library docs

javac reports the first point at which its model of your program stopped making sense, which is not always where you typed the mistake. Each report has the shape File.java:LINE: error: CLAIM, followed by the offending source line and a caret under the exact column, and for unresolved names two extra lines such as `symbol: variable conut` and `location: class Main`. Those two lines are the useful part, because they say what javac looked for and in which scope it looked, so `cannot find symbol` on a name you did declare normally means wrong case, wrong scope, or a missing import. A stray closing brace or a missing semicolon can produce twenty errors, so fix the first one and recompile before reading the rest: most of the others exist only because the parser lost its place.

A runtime failure prints one header line and then a list of frames. The header is `Exception in thread "main"`, then the fully qualified exception class, then the message after the colon: the class is the searchable name and the category of failure, while the message carries your actual values. The frames are the call chain captured when the exception object was constructed, innermost first, so a top frame like `at java.base/java.lang.Integer.parseInt(...)` does not mean the JDK is broken, it means parseInt was handed something its contract forbids; scan down to the first frame naming one of your files and start there. When a library wraps a failure, the original one is in the `Caused by:` block near the bottom, so read that block before the top one.

Every class page in the standard library docs is laid out the same way: package and type hierarchy at the top, a method summary table, then one detail entry per method with @param, @return and @throws. The @throws prose is what you need while reading a stack trace, because unchecked exceptions are often absent from the signature and only the text states the condition: parseInt refuses a leading or trailing space, and substring throws once the index passes the string's length. The docs are versioned, so check `java -version` and open the matching API page; the @since tag explains why an example copied from elsewhere fails with `cannot find symbol`, since String.repeat needs Java 11 and List.of needs Java 9. With no browser, `javap java.lang.Integer` prints the signatures straight out of the class file.

public class ErrorMessages {
    public static void main(String[] args) {
        int[] ports = {80, 443};

        try {
            System.out.println(ports[2]);
        } catch (ArrayIndexOutOfBoundsException e) {
            System.out.println("class  : " + e.getClass().getName());
            System.out.println("message: " + e.getMessage());
        }

        try {
            System.out.println(Integer.parseInt("8o80"));
        } catch (NumberFormatException e) {
            System.out.println("class  : " + e.getClass().getName());
            System.out.println("message: " + e.getMessage());
            System.out.println("parent : " + e.getClass().getSuperclass().getName());
        }
    }
}

Worked examples

public class TraceReading {
    public static void main(String[] args) {
        try {
            loadConfig("timeout=abc");
        } catch (IllegalArgumentException e) {
            StackTraceElement[] frames = e.getStackTrace();
            System.out.println("message: " + e.getMessage());
            System.out.println("top frame: " + frames[0].getMethodName() + " line " + frames[0].getLineNumber());
            System.out.println("depth: " + frames.length);
            System.out.println("bottom frame: " + frames[frames.length - 1].getMethodName());
        }
    }

    static void loadConfig(String line) {
        parseTimeout(line.substring(line.indexOf('=') + 1));
    }

    static void parseTimeout(String text) {
        for (int i = 0; i < text.length(); i++) {
            if (!Character.isDigit(text.charAt(i))) {
                throw new IllegalArgumentException("timeout must be digits, got '" + text + "'");
            }
        }
    }
}

import java.lang.reflect.Method;

public class SignatureLookup {
    public static void main(String[] args) throws NoSuchMethodException {
        Method parseInt = Integer.class.getMethod("parseInt", String.class);
        Method substring = String.class.getMethod("substring", int.class);

        System.out.println("parseInt returns " + parseInt.getReturnType().getName());
        System.out.println("parseInt declares " + parseInt.getExceptionTypes().length + " exception type(s)");
        System.out.println("substring returns " + substring.getReturnType().getName());
        System.out.println("substring declares " + substring.getExceptionTypes().length + " exception type(s)");
    }
}

Important notes

Common mistakes

Try it yourself