Fixing “Application Error: A Client-Side Exception Has Occurred”

When deploying a web app—especially on platforms like Vercel, Netlify, or Render—you might see this generic page:

Application error: a client-side exception has occurred.

This means your frontend JavaScript crashed in the browser. Below is a practical guide to diagnose and resolve it.

Quick Triage (5–10 Minutes)

1. Open DevTools → Console and Network tabs. Note the first red error and its stack trace.

2. Reproduce locally in production mode. Many errors hide in development builds.

   bashCopy

   1# Next.js
   2npm run build && npm run start
   3# Vite
   4npm run build && npx serve dist
   5# CRA
   6npm run build && npx serve -s build

3. If the error occurs only after deployment:

   • Confirm all environment variables exist on your host.
   • For Next.js, public vars must start with NEXT_PUBLIC_.
   • Clear browser cache, disable extensions, and reload.

Common Causes and Fixes

1. Accessing Browser-Only APIs During SSR (Next.js)

Symptom: window is not defined, document is not defined, or hydration mismatch. Fix:

1useEffect(() => {
2  // safe to access window here
3}, []);

Or disable SSR for a component:

1const Map = dynamic(() => import('./Map'), { ssr: false });

2. Unhandled Fetch or JSON Parse Errors

Symptom: Unexpected token < in JSON or crashes on bad responses. Fix:

1const res = await fetch(url);
2if (!res.ok) {
3  const text = await res.text();
4  throw new Error(`Request failed ${res.status}: ${text.slice(0,200)}`);
5}
6const data = await res.json();

3. Undefined Data or Props

Symptom: Cannot read properties of undefined (reading 'x'). Fix:

1const value = obj?.x ?? defaultValue;
2if (!router.isReady) return null; // for Next.js routing

4. Environment Variable Mismatch

Symptom: Works locally, fails after deploy. Fixes:

• Re-enter variables in your hosting dashboard.
• Redeploy to refresh build cache.
• Prefix client-side variables with NEXT_PUBLIC_.

5. Hydration Mismatches (Next.js)

Symptom: “Text content does not match server-rendered HTML.” Fix:

• Avoid rendering random or time-based values on the server.
• Move them inside useEffect.
• Ensure conditional rendering matches server and client output.

6. Compatibility Issues and Polyfills

If supporting older browsers, check your build target and ensure modern features (like optional chaining) are transpiled.

7. Add Error Boundaries (React/Next.js)

Prevent one broken component from crashing the whole app:

1class Boundary extends React.Component<any, {hasError:boolean}> {
2  state = { hasError: false };
3  static getDerivedStateFromError() { return { hasError: true }; }
4  componentDidCatch(err:any, info:any) { console.error(err, info); }
5  render() {
6    return this.state.hasError ? <Fallback /> : this.props.children;
7  }
8}

In Next.js 13+, use an error.tsx file per route segment.

8. Use Source Maps and Global Logging

Enable source maps to trace minified code:

1// next.config.js
2module.exports = { productionBrowserSourceMaps: true };

Capture uncaught errors early:

1window.addEventListener('error', e => console.error('Global error', e.error));
2window.addEventListener('unhandledrejection', e => console.error('Unhandled promise', e.reason));

Deployment-Level Checks

• Inspect build logs for warnings or missing variables.
• Validate Edge/Serverless responses—bad JSON or headers can crash the client.
• Confirm base URLs are correct (no localhost left in config).

Summary

“Client-side exception” means your browser JavaScript failed. Fixes usually involve:

• Correcting SSR/client code separation.
• Handling network and data safely.
• Verifying environment variables.
• Adding error boundaries and logging.

With the above checkpoints, you can move from a blank error page to a stable, traceable, and production-ready deployment.