Imagine CicloUrbano's server returns a bike without the pricePerHour field. BikeCard tries to do bike.pricePerHour.toFixed(2), JavaScript throws "Cannot read properties of undefined," and the result isn't a broken card: the entire application disappears. Header, catalogue, booking form, footer: a blank screen. Since React 16, an uncaught error during render unmounts the whole tree, and that deliberate behaviour makes a piece you don't know yet indispensable: the error boundary. In this lesson you'll learn what it is, how it's implemented (with the one React 19 exception that still requires a class component), where to place it, what kinds of errors it does not catch and what to do about those, and how to design a failure message that doesn't scare off whoever reads it.

1. What happens today when a component blows up
2. What an error boundary is
3. The two methods: getDerivedStateFromError and componentDidCatch
4. A complete ErrorBoundary for CicloUrbano
5. Where to place boundaries: global and granular
6. What error boundaries do NOT catch
7. Development versus production
8. react-error-boundary, the practical alternative
9. Logging the error to a monitoring service
10. Designing a good failure message

Let's trigger it on purpose. Add a broken bike to CicloUrbano's data:

BikeCard receives it and runs this line, which you already wrote in 02-05:

What you see in the browser with the app built for production:

And in the console:

Why does React unmount everything? The decision was made in React 16, and the reasoning goes like this: if a component has failed halfway through render, the tree is left in an inconsistent, unknown state. Leaving the interface half-done is worse than removing it: it could show wrong balances, buttons that trigger the wrong action, or forms that submit corrupt data. In a payments app, a corrupt interface is more dangerous than no interface at all.

But "blank screen" isn't an acceptable answer for the person using the app either. React's solution is to let you decide what to show instead, and that's the job of the error boundary.

An error boundary is a component that catches JavaScript errors thrown anywhere in its subtree of children, keeps the whole application from unmounting, and paints an alternative interface in its place.

The four properties that define its behaviour:

• It catches downward, not sideways. It protects its descendants, never its siblings or itself.
• It behaves like a JavaScript catch, but for components. The error "bubbles up" through the tree until it finds the first boundary.
• It replaces the entire subtree. When it catches, everything that hung off it unmounts and the alternative gets painted. There's no partial repair.
• If there's no boundary anywhere in the chain, the error reaches the root and React unmounts the application: the blank screen from section 1.

In this tree, a card's failure gets caught by the catalogue boundary: the bike list is lost and a message is shown instead, but the header, the booking form, and the footer keep working. That's the whole idea.

Here's the exception flagged back in 04-03 and 04-04: there is no hook equivalent. An error boundary has to be a class component, because the two methods that make it possible are only available on classes. React acknowledges this openly in its own documentation, and there's work in progress toward an alternative, but as of today — React 19 — the class is mandatory.

The two methods do different things, and it's worth not confusing them.

The ban on side effects isn't a suggestion: this method runs during render, which must be pure (04-03), and React can call it more than once for the same error. A log written here could get sent twice.

componentStack is the most valuable piece of information you'll get from a production failure:

It isn't the JavaScript call stack: it's the component path, and it tells you exactly which part of the interface failed.

Summary of the division of labour: getDerivedStateFromError paints; componentDidCatch logs. You can implement only the first one, but then you'll have no way of knowing what's failing in production.

Rundown of the design decisions:

• State holds two things: the hasError flag to decide what to paint, and the error itself, so it can show details or hand it to the fallback.
• render returns this.props.children untouched as long as there's no error. An error boundary is invisible in the normal case: it adds no markup, no styling, no rendering cost.
• fallback accepts two shapes. If it's JSX, it's painted as-is; if it's a function, it gets called with (error, retry) so whoever's using it can build a custom message with its own button. It's the render props technique from 04-02, applied where it genuinely pays off.
• The retry button does setState({ hasError: false }). That triggers a normal render, children mounts fresh again, and if the cause was transient — a malformed network response, say — the interface recovers. If the error is permanent, the boundary catches it again and the message shows once more: there's no infinite loop, because a person triggers the retry.
• role="alert" comes from 03-06: the message appears without anyone moving focus, and assistive technologies need to announce it.
• The constructor's bind is the one from 02-02: retry gets passed as a handler and would lose its this without it.

Notice that the fallback reuses the generic Notice from 04-02: composition again, without a single line of duplicated styling.

The recommended strategy combines two levels.

One global boundary at the root. It's the safety net of last resort: it guarantees a blank screen never appears, no matter what. It wraps <App /> in main.jsx and shows a full-app message, with the option to reload.

Several granular boundaries around the independent sections. The question that decides where to put one is always the same:

What part of the interface can be lost without the application stopping being useful?

In CicloUrbano there are three clear answers:

Practical criteria for deciding:

• Wrap what consumes external data. Anything that depends on an API is a candidate: malformed data is cause number one of render errors.
• Wrap what's third-party. A chart, a map, a player: code you don't control.
• Wrap every route. Once React Router arrives (Module 6), a boundary per route stops a failure on one screen from taking down the whole navigation.
• Don't wrap every component. A boundary per card looks safer, but it fills the code with noise and lets a failure disguise itself as a "broken card" instead of standing out. The right granularity is the section, not the element.
• Remember a boundary doesn't protect itself. If your fallback's JSX throws an error, the failure bubbles up to the boundary above it. Keep fallbacks simple: text, a button, and little else, with no calculations or access to fields that might be missing.

This section is the one that prevents a false sense of security. An error boundary catches only errors thrown during render, in lifecycle methods, and in the constructors of its subtree. Everything else is out of scope.

The reason is simple: a handler runs outside of render, once React isn't building anything anymore. A failure there doesn't leave the tree inconsistent, so React doesn't step in and the error just lands in the console.

The pattern is always the same: try/catch in the handler and its own error state that gets painted with the Notice from 04-02. It's more work than a boundary, but it also allows a much more precise message, because you know exactly which operation failed.

There's a trick to get an async error to a boundary: store it in state and rethrow it during render.

Use it sparingly, and only for errors that genuinely prevent the section from being shown; for everything else, an error state and a Notice give a better experience. In Module 7 you'll see that server-state libraries build this in by default.

One detail that confuses a lot of people the first time they try an error boundary: in development, the error is still visible.

Vite's red overlay shows up even though the boundary worked perfectly, and that's intentional: during development you want to hear about every error, not have it swallowed by a silent catch. Close it with Escape and you'll see your fallback underneath, already painted.

To really check the behaviour the public will see:

That build has no overlay, and you'll see exactly what the person using the app will see. It's a check worth running every time before signing off on a boundary: it's easy to write a fallback that itself fails — reading error.response.data, say — and not notice in development because the overlay hides the result.

Writing the class once is fine; writing it in every project, less so. The react-error-boundary library is the community's de facto standard, and it encapsulates everything from section 4, plus the part that's hardest to get right: the reset.

What it adds over the hand-rolled implementation:

resetKeys solves a real case: if the catalogue fails with the "Cargo" filter and the person switches to "Urban," it makes sense to retry just because of that change, without pressing any button.

Practical recommendation: write the class by hand once to understand the mechanism — which is what you just did — and use react-error-boundary in real projects.

A boundary that only paints a nice message leaves your team blind: production failures happen in browsers you're not in front of. That's why componentDidCatch matters so much.

Golden rules of error logging:

• Don't log in development. You'd fill the dashboard with noise from errors you're triggering yourself.
• Add business context. Knowing the failure was in the "catalogue" section with the "cargo" filter is worth more than a minified call stack.
• Never send personal data. usr-01's email, a session token, or a form's contents must never go out in an error report. Send identifiers, not data.
• Logging must never throw. The empty .catch() is intentional: an error inside the error handler is the worst kind of error.
• Upload the source maps. Without them, the production stack trace is unreadable. Upload them to the service, not to the public server.

In a real project you'll use a commercial service (there are several well-known ones) with its own SDK, but the pattern is identical: a single logging point called from componentDidCatch or from onError.

The boundary works; now the message needs to not ruin the experience. A failure message has four jobs: explain what happened, delimit the scope, offer a way out, and not scare people.

An example applied to CicloUrbano:

Four deliberate details:

• The title says what failed, in the language of the person using the app, not the program's.
• The second sentence delimits the damage. Knowing that only one section went down completely changes how the problem is perceived.
• There are two ways out: retry, and go do something else. A message with no way out is a wall.
• The incident id connects what the person sees with what your team sees on the monitoring dashboard, without showing technical details.

And an accessibility note, closing the thread from 03-06: the container carries role="alert" so it gets announced when it appears, and the message doesn't rely on the colour red to be understood.

• Expecting the boundary to catch an onClick. It never does. Handlers need their own try/catch and their own error state.
• Expecting it to catch a failed fetch. It doesn't either: async code is out of scope. Catch it with try/catch and store the error in state, or rethrow it during render if it's genuinely fatal.
• Putting side effects in getDerivedStateFromError. It runs during render and can get called more than once: logs would come out duplicated. That job belongs to componentDidCatch.
• A fallback that can also fail. If your message reads error.response.data.message and that field doesn't exist, the boundary throws inside itself and the failure bubbles up to the boundary above it. Keep fallbacks simple and proof against missing data.
• A single global boundary and nothing else. It succeeds at not leaving a blank screen, but any failure takes down the entire application. Add boundaries per section.
• A boundary per component. The opposite extreme: noise, tiny messages everywhere, and failures that go unnoticed.
• Testing only in development. Vite's overlay hides the result. Always check with npm run build && npm run preview.
• Tip: test your boundaries on purpose. Temporarily add a component that throws (function Bomb() { throw new Error('test'); }) inside each protected section and confirm the rest of the interface survives.
• Tip: a boundary doesn't replace validation. If you know pricePerHour can be missing, write bike.pricePerHour ?? 0 in the card. The boundary is the safety net for what you hadn't foreseen, not an excuse to skip checking data.

Exercise 1. Place CicloUrbano's error boundaries. Write main.jsx with the global boundary and the App.jsx excerpt with three granular boundaries (catalogue, bookings, and stations), each with its own title and its own call to reportError with the section's context. Explain why Header and Footer are left out.

Exercise 2. Classify these five CicloUrbano failures: does an error boundary catch them? If not, say how each one is handled.

1. BikeCard reads bike.pricePerHour.toFixed(2) and pricePerHour is undefined.
2. handleConfirm calls a fetch that returns a 500.
3. A setTimeout inside an effect throws an error two seconds later.
4. A legacy class component's constructor throws when it receives invalid props.
5. A boundary's fallback tries to read error.details.code and details doesn't exist.

Exercise 3. Write BookingsFallback, the booking interface for the booking panel's boundary. Requirements: reuse the Notice component from 04-02 with tone error; show a clear title; explain what keeps working; offer a "Try again" button and a link to the catalogue; show a short incident id generated with crypto.randomUUID().slice(0, 8); and be failure-proof (it must not throw even if error is null). Explain where the id must be generated and why it can't be generated in the component body.

Solution 1.

Header and Footer are left out for two reasons. First, they're practically static markup: they don't consume external data or run calculations on fields that could be missing, so their odds of failure are minimal. Second, if they failed anyway, losing navigation leaves the app unusable: there, a local fallback isn't what you want — you want the failure to bubble up to the global boundary and show a full-app message. A boundary gets placed where it makes sense to keep using the rest.

Solution 2.

Solution 3.

The id can't be generated in the component body for two reasons. The first is about correctness: crypto.randomUUID() in the body would return a different value on every render, so the reference the person sees would change every time the component repaints and would no longer match what got sent to the monitoring service. The second is conceptual: generating a random value during render makes it impure, and render must be pure (04-03).

The right place is the moment the error gets caught, meaning inside componentDidCatch, which runs exactly once per failure and does allow side effects:

That way, the same id travels to the monitoring service and shows up on screen: whoever calls support will give exactly the reference the team can look up. It's the same principle BookingForm follows in 03-05, generating its res-${crypto.randomUUID().slice(0, 8)} ids in the submit handler and not during render.

An error thrown during render unmounts React's entire tree and leaves a blank screen. Error boundaries are the answer: components that catch failures in their subtree and paint an alternative interface. They're implemented with two methods that, as of today, only exist on class components — static getDerivedStateFromError to decide what to paint and componentDidCatch to log — and that's the one exception left to the rule that everything gets written with functions and hooks. You've built ErrorBoundary for CicloUrbano with a customizable fallback and a retry button, placed it on two levels — one global in main.jsx and several granular ones per section — and you know it does not catch event handlers, async code, or its own failures, along with the right technique for each case. Add to that logging to a monitoring service with business context, react-error-boundary as a practical option for everyday work, and failure messages that explain, delimit, and offer a way out.

This closes out Module 4. Across four lessons the project has changed scale: state moved up to the common ancestor and the catalogue genuinely filters (04-01); the interface got recomposed with containers, named slots, and specializations instead of inheritance (04-02); you learned to read the classic lifecycle and translate it (04-03); and you laid out the full map of hooks along with the rules that govern them (04-04).

Now it's time to walk that map in detail. Module 5: React Hooks dedicates one lesson to each tool: useState in full depth with all its nuances, useEffect and the synchronization model announced in 04-03, useRef for what gets remembered without repainting, useContext to put an end to the prop drilling left open in 04-01, useReducer for complex state, and finally custom hooks, where your own logic turns into a reusable function without a single wrapper. The next lesson is The useState Hook.