Error Handling

Error handling is how a Node.js program detects, reports, and recovers from things going wrong — using try/catch for synchronous and async/await code, error-first callbacks, and the Error object to carry details.

Learn Error Handling in our free Node.js course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a quick reference.

Part of the free Node.js course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

By the end of this lesson you'll know how to throw and catch errors, how to handle failures in promises and callbacks (and the trap where try/catch silently misses them), and how to define your own error types and add a process-level safety net so an unexpected failure doesn't take your whole app down without a trace.

What You'll Learn in This Lesson

1️⃣ try / catch / finally and throwing

When something goes wrong you throw an Error object . Throwing immediately stops the current function and jumps to the nearest catch . You wrap risky code in a try block, handle the failure in catch (err) , and put cleanup that must always run in finally .

• • throw new Error('msg') — raises an error carrying a message (and a stack trace).
• • err.message — the human-readable text you passed to new Error() .
• • err.stack — the call stack with file names and line numbers, for debugging.
• • finally { } — runs whether the try succeeded or threw, so it's perfect for closing files or releasing resources.

Read the worked example below — every line is explained — then run it and compare with the expected output.

2️⃣ Handling Errors in Async Code

Asynchronous code fails in a few different shapes, and the way you catch it depends on the shape. The big trap for beginners: a plain try/catch only catches what happens while it is running , so an error thrown later inside a callback slips right past it.

• • async/await — wrap the await in try/catch ; a rejected promise is re-thrown at the await line.
• • promises — attach .catch(err => ...) to handle a rejection without async/await.
• • error-first callbacks — check the first argument first: if (err) return ... .
• • the trap — a throw inside a setTimeout or event callback is not caught by an outer try/catch, because the callback runs after the try has already exited.

Read the comments carefully — example 4 shows exactly why the outer catch never fires.

Your turn. The program below works once you fill in the three blanks marked ___ . Follow the 👉 hints, then run it and compare with the expected output.

3️⃣ Custom Errors & Process-Level Safety Nets

For bigger programs you'll want to tell error types apart. A custom error class extends the built-in Error , so you can check err instanceof ValidationError and attach extra fields like which input failed. And for the failures that escape every handler, Node gives you two last-resort process events.

• • class ValidationError extends Error — a named error type you can recognise and react to specifically.
• • process.on('uncaughtException', fn) — fires when a synchronous error escapes every try/catch.
• • process.on('unhandledRejection', fn) — fires when a rejected promise has no .catch() .

Treat the process handlers as smoke detectors: log the failure, shut down gracefully, and let a process manager restart you. They are a safety net, not your everyday error handling.

Mini-Challenge: A Safe JSON Parser

No blanks this time — just a brief and an outline to keep you on track. Write it yourself, run it, and check your output against the example in the comments. Parsing untrusted input is exactly where real apps crash, so this is a habit worth building.

Common Errors (and the fix)

• Swallowing errors silently — an empty catch (err) { } hides the failure and makes bugs impossible to trace. At minimum, log err.message ; usually you should also handle or re-throw it.
• Throwing non-Error values — throw 'oops' loses the stack trace and breaks code that reads err.message . Always throw new Error(...) (or a subclass).
• Forgetting to handle promise rejections — a promise with no .catch() (or no try/catch around its await ) triggers an unhandledRejection and can crash the process.
• Assuming try/catch catches async callbacks — a throw inside setTimeout or an event handler runs after the try has exited, so the outer catch never sees it. Handle the error inside the callback.
• Not re-throwing or logging — if a catch block can't actually recover, don't bury the error. Log it, or re-throw with throw err so a caller (or your safety net) can deal with it.

Pro Tips

• 💡 Prefer async/await with try/catch over long .then().catch() chains — the error flow reads top-to-bottom like synchronous code.
• 💡 Add context when you re-throw: wrap a low-level error in a clearer one (and set the new error's cause ) so logs explain what you were doing, not just what broke.
• 💡 Use custom error classes so callers can branch on instanceof instead of matching fragile message strings.

📋 Quick Reference — Error Handling

Concept

Node.js Syntax

Throw an error

throw new Error(msg)

Catch an error

try { } catch (err) { }

Read the message

err.message

Always-run cleanup

finally { }

Custom error type

class X extends Error

Async safety net

process.on('unhandledRejection', fn)

Frequently Asked Questions

🎉 Lesson Complete!

• ✅ throw new Error('msg') raises a failure; try { } catch (err) { } handles it
• ✅ err.message and err.stack carry the details you need to debug
• ✅ finally { } always runs — perfect for cleanup
• ✅ Wrap await in try/catch; use .catch() for promises and if (err) for callbacks
• ✅ A throw inside an async callback escapes an outer try/catch — handle it where it happens
• ✅ Custom errors ( extends Error ) and process.on('unhandledRejection') are your last lines of defense
• ✅ Next lesson: Express Intro & Routing

Practice quiz

Continue this course

• Previous: Async Patterns (callbacks → promises → async/await)
• Next: Express Intro & Routing