HTTP Error Fixes in Node.js and Next.js

Why Node apps fail differently

A PHP site starts a fresh worker for each request, so a fatal error usually spoils only that one page. A Node app is one long-running process that handles every request. That design is fast, but it changes what errors do:

• One uncaught error can stop everything. If an exception escapes your handlers, Node's default is to print it and exit. Until a process manager starts it again, nothing is listening and the proxy in front returns 502 for every URL.
• Status codes are whatever your code says. Many frameworks default to 200. If a route renders "Product not found" without setting the status, the page is a soft 404.
• Rendering can start before errors happen. With streamed server rendering, the 200 status and the top of the page may already be on their way when a component deeper down fails, so the code cannot be changed any more.
• Hosting platforms add their own limits. Serverless and edge functions have maximum run times and memory. Going over produces an error from the platform, not your app.

Because the audit sees the outside of the app, the first job is always to compare what the HTTP Error Audit reports with what your code thinks it is doing.

The fix, step by step

A safe Express error set-up

This pattern covers steps 2 and 3 in one place. The order of the middleware matters: routes first, then the 404 catch-all, then the error handler, which Express recognises because it takes four arguments.

const express = require('express');
const app = express();

// Express 4 only: pass async errors on to the error handler
const wrap = fn => (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);

app.get('/products/:slug', wrap(async (req, res) => {
  const product = await db.products.findBySlug(req.params.slug);
  if (!product) return res.status(404).render('not-found');
  res.render('product', { product });
}));

// Anything no route matched
app.use((req, res) => res.status(404).render('not-found'));

// Every error ends up here
app.use((err, req, res, next) => {
  console.error(req.method, req.originalUrl, err);
  if (res.headersSent) return next(err);
  res.status(err.status || 500).render('error');
});

app.listen(3000, '127.0.0.1');

The headersSent check matters when a response was already partly sent, for example while streaming a file. Passing the error on lets Express close the connection rather than trying to send a second set of headers, which would throw another error.

Next.js status codes in practice

Next.js gets most status codes right when you use its own functions, and wrong when you imitate them with ordinary components.

With streaming, once Next.js has begun sending the page it cannot change the status. If notFound() is reached inside a part of the page that renders later, inside a Suspense boundary, the response has already gone out as 200; Next.js adds a noindex robots tag in that case, but the code stays wrong. Load the data that decides whether the page exists at the top of the page component, before anything is streamed, so the check runs first.

Static exports built with output: 'export' have no server of their own. The host decides the status, so configure it to serve your generated 404.html with a 404 code for unknown paths rather than serving index.html with 200.

Reading PM2 when the site shows 502

When a self-hosted Node site suddenly returns 502 on every page, the proxy in front is almost always fine and the Node process is down or restarting. PM2 tells you which within a minute.

pm2 list                  # status, restart count and memory per process
pm2 describe app-name     # script path, working folder, log file locations
pm2 logs app-name --lines 200 --err   # the last errors before each restart

• Status "errored" or "stopped": PM2 gave up. The error log shows why the process could not start: a missing build, a missing environment variable, or a port already in use.
• Status "online" but the restart count keeps rising: the app crashes and PM2 brings it back. Visitors get 502s during each gap. Find the crash in the error log.
• Memory creeping up until a restart: a leak, or a cache held in memory with no size limit. max_memory_restart buys time while you find it.
• Online and stable, but still 502: the app is listening on a different port or address from the one the proxy uses. The 502 Bad Gateway guide covers matching the two, and the idle connection timing that causes occasional 502s behind load balancers.

A minimal ecosystem.config.js keeps these settings in the repository rather than in someone's shell history:

module.exports = {
  apps: [{
    name: 'shop-web',
    cwd: '/srv/shop/current',
    script: 'node_modules/next/dist/bin/next',
    args: 'start -p 3000 -H 127.0.0.1',
    instances: 2,
    exec_mode: 'cluster',
    max_memory_restart: '600M',
    env: { NODE_ENV: 'production' }
  }]
};

Hosted platforms and their limits

On managed platforms you do not run PM2 or nginx, but the same failures appear with different names. The platform's function or runtime logs are the equivalent of the server error log, and each platform documents its own error codes.

• Run-time limits. Functions that take too long are stopped and the platform returns a timeout error, typically a 504. Limits differ by platform, plan and runtime and have changed over time, so check the current documentation rather than relying on a number you remember.
• Memory limits. Functions that exceed their memory are killed, often logged as an out-of-memory or runtime exit error, and surface as 500 or 502.
• Edge runtime restrictions. Code running at the edge, including Next.js middleware on many hosts, cannot use every Node API. A library that needs the file system or native modules can build fine and then fail on the first request.
• Environment variables. A variable set for preview deployments but not production is a common cause of a 500 that appears only on the live site.
• Cold starts. The first request after a quiet spell can be slow while the function starts. That usually shows as a slow response rather than an error; the timeout errors guide covers what to do when it crosses into a failure.

Preventing repeat failures

• Add automated tests that request a missing path and a missing record and assert a 404, and trigger an error and assert a 500.
• Send errors to a logging or error-tracking service so you see crashes before visitors report them.
• Expose a /healthz route that checks the database connection, and point your uptime monitor and load balancer at it.
• Treat a rising PM2 restart count as a bug report, not a sign that restarts are working.
• Keep deploys atomic: build, test, switch, reload, with the previous release kept for rollback.
• Run the HTTP Error Audit after each release, as many status code mistakes only show on routes nobody clicks in testing.