How to Read a Stack Trace Without Panicking
A stack trace tells you exactly where a program failed and how it got there. Learn to read one top to bottom and find the cause fast.
By Velloreth
What a stack trace is
A stack trace is a snapshot of the call stack at the moment an error occurred. It lists the function calls that were active, from the point of failure back to the program’s entry point.
TypeError: Cannot read properties of undefined (reading 'name')
at formatUser (/app/src/user.js:42:18)
at renderProfile (/app/src/profile.js:17:9)
at handleRequest (/app/src/server.js:88:5)
at Server.emit (node:events:518:28)
at parserOnIncoming (node:_http_server:601:12)
Read it as: formatUser failed at line 42, called from renderProfile at line 17, called from handleRequest at line 88, and so on up to the HTTP server.
The top frame is where the error happened. The frames below are how the program got there.
Reading it in order
1. The exception type and message.
TypeError: Cannot read properties of undefined (reading 'name')
This is the most informative line. It says: something was undefined, and the code tried to read .name from it. That is the cause, stated plainly.
2. The top frame.
at formatUser (/app/src/user.js:42:18)
The error was thrown in formatUser, at line 42, column 18. Open that file at that line.
3. The first frame in your code.
In the example, the top frame is already your code. But often it is not:
TypeError: x is not a function
at Object.<anonymous> (/app/node_modules/lodash/lodash.js:1234:5)
at map (/app/node_modules/lodash/lodash.js:567:8)
at processUsers (/app/src/users.js:23:12)
at main (/app/src/index.js:9:3)
The error is inside lodash, but the cause is how processUsers called it. The first frame in your code — processUsers at line 23 — is where to look.
4. The frames below.
These show the call chain. They are useful when the bug is not at the failure point but in how the program arrived there. A wrong value passed three frames up is a common pattern.
Library frames are usually noise
A stack trace from a real application is mostly framework code.
at Layer.handle [as handle_request] (/app/node_modules/express/lib/router/layer.js:95:5)
at next (/app/node_modules/express/lib/router/route.js:144:13)
at Route.dispatch (/app/node_modules/express/lib/router/route.js:114:3)
at /app/node_modules/express/lib/router/index.js:284:15
at Function.process_params (/app/node_modules/express/lib/router/index.js:346:12)
at Immediate.next (/app/node_modules/express/lib/router/index.js:280:10)
at Immediate._onImmediate (/app/node_modules/express/lib/router/index.js:280:10)
None of this is the bug. It is Express routing to your handler. The interesting frame is the one with /app/src/ in the path.
The habit: scan for the first frame whose path is your code, and start there.
Caused by chains
Java, Python, and some other runtimes chain exceptions.
java.sql.SQLException: Connection refused
at com.mysql.jdbc.ConnectionImpl.connect(ConnectionImpl.java:1234)
...
Caused by: java.net.ConnectException: Connection refused (Connection refused)
at java.net.PlainSocketImpl.socketConnect(Native Method)
...
Caused by: java.net.UnknownHostException: db.internal
at java.net.InetAddress.getAllByName0(InetAddress.java:1281)
Read the chain from the bottom up. The deepest Caused by is the root cause: the hostname db.internal could not be resolved. The outer exceptions are consequences — the connection failed because the host was unknown.
Fixing the outer symptom without reading to the bottom leads to wasted effort. The fix is the DNS entry, not the connection pool.
Common exception types
| Exception | Usually means |
|---|---|
TypeError | Wrong type, or a value is null/undefined |
ReferenceError | A variable is not defined |
NullPointerException | A reference is null |
IndexOutOfBounds | An index is outside the array |
KeyError | A dictionary key is missing |
ValueError | A value has the right type but a bad value |
ECONNREFUSED | Nothing is listening on the port |
ENOENT | A file or directory does not exist |
EADDRINUSE | The port is already in use |
Recognising these speeds up diagnosis considerably. ECONNREFUSED is almost always a service that is not running; ENOENT is almost always a wrong path.
Minified traces
Production JavaScript is minified, so the trace looks like this:
TypeError: t is not a function
at n (main.a1b2c3.js:1:45231)
at r (main.a1b2c3.js:1:45890)
The names are meaningless and the line numbers point at line 1. Source maps fix this. Most bundlers generate them, and browsers apply them automatically when DevTools is open. For server-side errors, tools like Sentry and Datadog use the source maps to show the original code.
If you see a minified trace and no source map, the first step is to enable source map generation in the build.
Truncated traces
Runtimes limit the frames shown.
Node: --stack-trace-limit=50 increases the limit.
Java: -XX:MaxJavaStackTraceDepth=100 does the same.
Python: traceback.print_stack(limit=None) prints everything.
Repeated frames are often collapsed with ”… 20 more”. That is usually fine, but if the recursion depth matters, raise the limit.
Async stack traces
In async code, the stack can be misleading, because the call that scheduled the work is not on the stack when it runs.
async function load() {
const data = await fetchData(); // stack here does not include the caller
return process(data);
}
Modern runtimes have improved this. Node’s --async-stack-traces flag (on by default in recent versions) links async frames, and browsers show “async” markers in the trace. Without it, you see only the frames from the current microtask.
When an async trace looks incomplete, the missing context is usually the scheduling call. Adding a log at the point of scheduling helps.
A practical workflow
1. Read the message. It usually names the cause.
2. Find the top frame. Open that file at that line.
3. Find the first frame in your code if the top is a library.
4. Check the values at that line. What is null, undefined, or the wrong type?
5. Walk up the stack if the value was passed in. Where did it come from?
6. Fix the cause, not the symptom. A null check at the failure point often hides the real bug upstream.
Step 6 is the one people skip. Adding if (user) at line 42 stops the crash but leaves the question of why user was undefined. The answer is usually more valuable than the guard.
Practical guidance
- Read the exception message first — it usually names the cause.
- Start at the top frame, then find the first frame in your own code.
- Ignore library frames unless the library is genuinely at fault.
- Read
Caused bychains from the bottom up. - Enable source maps for production JavaScript.
- Raise the stack limit if the trace is truncated.
- Fix the cause, not the symptom — a guard at the failure point hides the real bug.
For the related techniques, see debugging strategies that work and debugging with breakpoints. For the broader context, error handling patterns that actually work and incident response for solo developers.
Quotable summary
A stack trace is a snapshot of the call stack at the moment of failure, showing the exact line and the chain of calls that reached it. Read the exception type and message first, since they usually name the cause, then the top frame for where it was thrown, then scan down for the first frame in your own code, because library frames are usually noise. In Caused by chains, read from the bottom up: the deepest cause is the root, and the outer exceptions are consequences. Minified traces need source maps to be readable, and truncated traces can be extended with a runtime flag. The most common mistake is fixing the symptom at the failure point rather than the cause upstream.