How to Fix HTTP Errors in Node.js / Next.js
Node.js and Next.js HTTP errors (4xx, 5xx) need framework-specific handling: not-found pages, error boundaries, API route try/catch, edge function failures. This guide covers the Node.js/Next.js HTTP error workflow. Pair with HTTP error guide.
Step-by-step: How to fix Node.js / Next.js HTTP errors
- Audit current error pages. Visit /this-page-doesnt-exist on your Next.js site. Should return 404 with custom page. Visit a known broken page or trigger an error — should return 500 with custom page. If you see framework defaults, customise.
- Customise 404 (App Router). Create app/not-found.tsx → exports default NotFound function returning JSX. Triggered when notFound() called or no route matches. Customise messaging, links to popular content, search.
- Customise 500 (App Router). Create app/error.tsx → 'use client' directive, exports default Error function receiving error and reset props. Renders for uncaught errors in client components. Add app/global-error.tsx for layout-level errors.
- Handle API route errors. Next.js API routes (app/api/*/route.ts or pages/api/*.ts): wrap handler logic in try/catch, return Response with proper status code: return new Response(JSON.stringify({error: 'message'}), {status: 500, headers: {'Content-Type': 'application/json'}}).
- Audit edge function failures. Edge runtime (middleware.ts, edge API routes) has restrictions: no Node.js APIs, limited memory, timeout. Failures often silent. Vercel logs → Edge Functions tab. Self-hosted: add monitoring (Sentry edge runtime support).
- Add error monitoring. Sentry, Rollbar, LogRocket. Wraps Next.js with error capture. Catches client errors, SSR errors, API route errors, edge function errors. Per-deployment release tracking matches errors to deploys.
- Monitor production. Vercel deployment URL → Logs tab → Errors filter. Self-hosted: pm2 logs, journalctl, or wherever your stdout/stderr ships. Track 5xx rate; spike investigation immediately.
Frequently Asked Questions
Why does my Next.js return 500 sometimes but works in dev?
Production-only errors usually mean: 1) env var missing in production (process.env.X undefined → crash). 2) Server-only code accidentally importing client code. 3) Database connection pooling issues at scale. 4) Memory limits on serverless (Vercel function timeouts). Always reproduce in production-like environment before debugging.
How do I add custom 404 page in Next.js App Router?
Create app/not-found.tsx. Component renders for any unmatched route. To trigger 404 from a page (e.g., when data fetch returns null): import { notFound } from 'next/navigation'; notFound(); — Next.js displays your not-found.tsx and returns 404 status.
Best Node.js / Next.js error monitoring?
Sentry — most popular, full-stack error tracking with Next.js integration. Vercel Observability (built-in for Vercel users). Rollbar, Datadog, LogRocket as alternatives. Sentry's Next.js SDK auto-captures SSR errors, client errors, API route errors with minimal setup.
How do I handle errors in Next.js Server Actions?
Server Actions (Next.js 14+) can throw errors that surface to the client. Wrap in try/catch, return result objects { ok: true, data } or { ok: false, error } rather than throwing. Client checks result.ok and displays errors. Sentry captures uncaught Server Action errors automatically.
Why does Vercel report 'Function execution timed out'?
Vercel Serverless Functions have execution limits (10s default for Hobby, 60s Pro, 900s Enterprise). Long-running operations (heavy DB queries, large file processing, external API timeouts) exceed limits. Solutions: increase function timeout (config), optimise the operation, move to background job (Vercel Cron, queue), or stream response.