Fixing JavaScript Errors in React and Next.js

Why React errors look different

A production React build strips out its long explanatory messages to save space. Instead of a sentence, you get something like Minified React error #418; visit https://react.dev/errors/418 for the full message. The number is a code for the full text, and the link explains it. The development build, which you run locally, prints the complete message, the component that caused it and a component stack showing where it sits in the tree.

React also changes what happens after an error. In a plain script, an uncaught error stops one task and the rest of the page carries on. In React, an error thrown while rendering a component, and not caught by an error boundary, removes the entire component tree from the screen. On a site where React renders the whole page, that means a white screen, both for visitors and for any crawler that renders the page.

Frameworks such as Next.js add a third place for errors to happen: the server. Code runs once on the server to produce HTML, then again in the browser to hydrate it. An error can appear in either place, or come from the two runs disagreeing, and each needs a different fix.

Common React and Next.js errors and where they come from

Fixing hydration mismatches properly

Hydration expects the browser's first render to produce exactly the HTML the server sent. Anything that can differ between the two runs will break that. The fix is always to make the first render deterministic, then change anything browser-specific afterwards.

Dates, times and random values

A server in one time zone and a visitor in another will format the same date differently. Math.random() and Date.now() give different answers each time. Either format dates on the server with a fixed time zone and pass the finished string down, or render a neutral placeholder first and fill in the local value after mounting.

'use client';
import { useEffect, useState } from 'react';

export function LocalTime({ iso }) {
  const [text, setText] = useState(null);
  useEffect(() => {
    setText(new Date(iso).toLocaleTimeString('en-GB'));
  }, [iso]);
  return <time dateTime={iso}>{text ?? 'Today'}</time>;
}

Checks for the browser during render

Code such as typeof window !== 'undefined' ? A : B inside the render body produces B on the server and A in the browser. Move the check into an effect, as above, so both sides render B first.

Invalid HTML nesting

Browsers repair some invalid HTML as they parse it. A <div> inside a <p>, a link inside a link, or a table without its body element will be rearranged by the browser, so the structure React finds no longer matches. The development build names the offending elements; fix the markup.

Using suppressHydrationWarning

The suppressHydrationWarning prop silences the warning for one element's own text or attributes, one level deep. It is meant for values that are expected to differ, such as a timestamp. It does not fix anything, and using it on a wrapper to hide wider mismatches leaves the underlying problem in place.

Browser-only code and server rendering

Anything that uses window, document, localStorage or navigator only exists in the browser. When that code runs during server rendering or a static build, it throws. Three patterns cover almost every case:

• Use browser objects inside effects or event handlers. Effects never run on the server, so useEffect is a safe place to read storage or measure the window.
• Import browser-only libraries lazily. Some map, chart and editor libraries touch the browser as soon as they are imported. Load them with a dynamic import() inside an effect, or with next/dynamic and ssr: false from a client component.
• Keep module-level code clean. A line at the top of a file such as const width = window.innerWidth runs when the module loads, on both sides. Move it into a function that runs in the browser.

'use client';
import dynamic from 'next/dynamic';

const StoreMap = dynamic(() => import('./StoreMap'), {
  ssr: false,
  loading: () => <p>Loading map…</p>,
});

Environment variables that vanish in the browser

Next.js only includes environment variables in client-side code when their names start with NEXT_PUBLIC_. Everything else stays on the server, which is deliberate: it keeps secrets such as API keys out of the browser. A component that reads process.env.API_URL will work during server rendering and get undefined in the browser, which often leads to a failed request to an address like undefined/products.

• Rename values the browser genuinely needs, such as a public API base address or an analytics ID, with the NEXT_PUBLIC_ prefix.
• Never add the prefix to secret keys. Call a server route or server action that uses the secret instead.
• Public values are written into the JavaScript at build time. Changing them in your hosting dashboard has no effect until you rebuild and redeploy.
• Reference each variable by its full name. Reading variables through a dynamic lookup such as process.env[name] is not replaced at build time.

Vite-based React projects follow the same idea with a VITE_ prefix and import.meta.env; Create React App used REACT_APP_.

The fix, step by step

Error boundaries in practice

An error boundary is a component that catches render errors in the components below it and shows a fallback. React still requires a class component to write one yourself, though many projects use the small react-error-boundary package instead. Next.js App Router projects get boundaries per route segment by adding an error.js file, which must be a client component.

// app/products/[slug]/error.js
'use client';

export default function ProductError({ error, reset }) {
  return (
    <div role="alert">
      <p>Sorry, this part of the page could not load.</p>
      {/* A "Try again" button whose click handler calls reset() */}
    </div>
  );
}

The reset function asks Next.js to render the segment again, so wire it to a button's click handler to give visitors a retry. Boundaries have limits worth knowing. They catch errors during rendering, in lifecycle methods and in constructors below them. They do not catch errors in event handlers, in asynchronous code such as a timer or a fetch callback, or in the boundary itself. Handle those with ordinary try and catch, and set state so the next render can show a message.

Where you place boundaries decides what visitors lose. One boundary around the whole app turns a white screen into a friendly error page, which is better but still loses everything. Smaller boundaries around optional sections, such as reviews or related products, let the main content and the buy button survive when a secondary widget fails.

Edge cases

• Two copies of React. Hook errors that make no sense often mean a package brought its own copy of React. Run npm ls react and make sure only one version appears.
• Errors only after client-side navigation. The first load is server-rendered but later pages render in the browser, so browser-only bugs can hide on the landing page. Test by clicking through the site, not only by loading pages directly.
• Development-only double effects. Strict Mode runs effects twice in development to expose missing clean-up. If something breaks only locally because of this, the fix is usually a proper clean-up function, not removing Strict Mode.
• Stale deployments. Visitors with an old tab open may request code chunks that a new deploy removed, causing chunk load errors. Keep previous build assets available for a while after each release.