How to read a Java stack trace on Mac: find the real cause, for beginners

A stack trace is Java's record of where a program was when something went wrong. The JVM prints one when an exception is thrown and nothing in the code catches it. You will see it in Terminal, in the run panel of your editor, in a test report, or in a log file. The format is the same in all of these places. Learn to read it once, and you can read a trace from a web server, a unit test, or a command line tool.

The four parts of a Java stack trace

1. The exception line. It holds the exception class, such as java.lang.NullPointerException, then a colon and a message.
2. Stack frames. Each line starts with at. It names a class, a method, and the source file with a line number in parentheses.
3. Caused by lines. A Caused by line means one exception wrapped another. Each one starts a new block of frames below it.
4. More lines. The JVM hides frames that repeat from the enclosing trace and shows a short line that says more, with a count.

Read the frames from the top down. The first frame is where the exception was created. Each frame below it is a call that led to that point. The bottom frame is usually the entry point of the program, such as main.

How to read a Java stack trace, step by step

1. Copy the whole trace. Drag across it in Terminal and press ⌘ C, or select it in your editor's run panel.
2. Read the exception class and message. A helpful NullPointerException message usually names the variable that was null.
3. Find the first frame from your own code. Your package is the reverse domain at the start of your class names, such as com.yourcompany.
4. Open that file. In VS Code or Cursor, press ⌘ P, type the file name, then press ⌃ G and type the line number.
5. Read the lines around that number. Note which variable could be empty, wrong, or out of range.
6. Move to the bottom Caused by line and read the root exception the same way.
7. Reproduce the failure with the smallest input you can find, then change one thing at a time.

Write down three things before you touch the code. Record what the message says, which file and line it points at, and which value looked wrong. That note keeps you from chasing guesses.

Find your own code in a long stack trace

Long traces are mostly framework and JDK frames. Frames that start with java., javax., or jdk. belong to Java itself. Library frames carry their own package names. Scan down until you see a package you recognize as yours, then stop there.

Treat that first frame as a suspect, not a verdict. Your code may be correct and still receive a bad value from its caller. Read one frame up to the caller, then ask where the bad value came from. That question usually leads to the real bug.

Modern Java versions usually name the null variable in a NullPointerException message. Older traces only show the line. In both cases, the message tells you what was null, not why it became null. You still have to trace the value back.

How to follow the Caused by chain in Java

A Caused by line means a lower layer failed first. Your code or a library caught that failure and threw a new exception that wraps it. Java prints the original below the wrapper. Start at the bottom Caused by line. The root exception often names the true failure, such as a missing file or a refused connection.

Here is a small example. The top line says an import failed. The Caused by line below says a file was not found, followed by a path. You now know to check the path and the file, not the import code. The wrapper showed where the failure surfaced. The root showed what failed.

Worked example: a null value from a customer lookup

Say the top line reads NullPointerException, and the message says a String is null where length is called. The first frame from your code is Invoice.total. The frame above it is Report.build, which calls total with an invoice from a customer lookup. Open Invoice.total first, and find the field that is null.

Now you have two questions. Why does total assume the name is set? Why did the lookup return a customer with no name? The second question is the real bug. The fix belongs in the lookup or in data validation, not in total. The trace showed where the crash happened. It did not show where the bad data started.

Java stack trace on a Mac: where to search

• Terminal: press ⌘ F to search the output for a class name. You can also find the same bar under Edit > Find > Find.
• Editor: press ⇧ ⌘ F in VS Code or Cursor to search every file for a class or method name.
• Chrome: press ⌘ L to jump to the address bar. Paste the exception class and the first few words of the message in quotes.
• Console: a normal Java exception prints to the output and does not create a crash report. If the whole Java process crashes, open Console and check Reports in the sidebar.

Console sorts reports into user reports and system reports. You can see the user reports for apps you use. Only an administrator can view every report. Crash report files end in .ips, so use the file name and the time stamp to match a report to the run that failed.

Common mistakes when reading stack traces

• Reading only the top line and guessing a fix.
• Editing JDK or framework code, which you usually cannot change, instead of your own call site.
• Trusting a line number from an old build. Clean the project and rebuild first.
• Logging only the message. The message drops the stack and the Caused by chain. Log the whole exception object instead.
• Pasting a trace with tokens, emails, or customer IDs into a chat tool without removing them.
• Accepting an AI explanation without opening the file it names.

Where Lazur helps while you read a trace

Lazur is a voice assistant that lives in the notch on your Mac. Hold ⌥ ⌘ and ask what the trace means. Lazur sees your screen while you hold the shortcut and answers out loud. Ask where the first line from your code is, and Lazur draws a circle and a label around it.

Lazur has limits, and they matter for this job. It does not click through Cursor, run your build, or edit your files. Its guide mode walks you through one step at a time and waits for each click. The reading, the reasoning, and the fix still belong to you. Treat its explanation as a lead to check against the code.

Turn the trace into a clear bug report

Once you know the cause, the report is the next job. Paste the trace into a Linear issue or a Slack message. In Slack, wrap it in triple backticks so the layout holds. Add two lines above it that describe what you expected and what happened. Hold fn to dictate those lines at the cursor in any app. See AI dictation for developers for more.

Privacy and work rules for pasted traces

Traces often contain customer emails, internal hostnames, file paths, and tokens. Remove them before you paste into Slack, Linear, or an AI tool. Lazur listens and looks at the screen only while you hold the shortcut. Audio and the screenshot go to AI providers to answer and are not stored. Content is never used to train AI models.

If you work with client records, patient data, or other regulated information, follow your employer's rules first. Some rules forbid pasting that data into any outside tool. When you are unsure, redact the trace or ask your team before you share it.

Next steps for reading errors faster

Start with one trace from your own project this week. Use the order in this guide, and write the note before you change code. The VS Code guide and the Cursor guide cover the shortcuts used here. For the full list of ways Lazur helps with errors, see Lazur for developers. Trial details are on the pricing page.