Next.js code runs in three places, and errors look different in each. At build time: the build fails, and the build log shows the error (type errors, failed data fetching, missing environment variables). On the server: pages return 500 errors, and the details are in your host's server or function logs. In the browser: the page breaks after loading, and the browser console shows it. Next.js uses error boundaries (error.js files) to show a fallback instead of a broken page when something throws.
What's the problem
A Next.js build fails, pages show "Application error: a server-side exception has occurred" or a 500, or parts of the page break in the browser.
Why it happens
- Build errors: TypeScript or lint errors, a dependency problem, or data fetching that fails during the build.
- Missing environment variables in production, especially ones the browser needs (which must be exposed at build time).
- Server errors in server components, route handlers or server actions: a failing database or API call.
- Browser-only errors: code using
windowor browser APIs during server rendering, or hydration mismatches. - Upgrades changing behaviour between Next.js versions.
How to fix it
- Work out where it fails: build log, server logs, or browser console.
- For build failures, run
next buildlocally from a clean install to reproduce. - For server errors, find the request in your host's logs and read the stack trace.
- Check environment variables for production and rebuild after changing them.
- Add
error.jsboundaries so a failing section shows a fallback. - After upgrading, read the upgrade guide for breaking changes.
What Preventionlabs checks
One click runs the full report on your domain. For this problem it shows whether your site loads, how fast, and where its redirects go; up to 50 pages from your sitemap, listing any that fail or are slow, plus broken links on them. With Cloudflare connected, it also shows which pages returned server errors (5xx) to visitors, and when; recent deploys and account changes, with their times. It doesn't read your server logs, so the exact error message is in your host's logs.
Run your free reportYour first report is free, no card needed. Then A$50 a month, up to 10 domains. Read-only: it never changes anything.
Sources
- Next.js: Error Handlingofficial docs
Uncaught exceptions are unexpected errors that indicate bugs or issues that should not occur during the normal flow of your application. These should be handled by throwing errors, which will then be caught by error boundaries.
Preventionlabs is independent and not affiliated with Next.js. Product names are used only to describe the problem.
← All of Frameworks