Fix common Node.js errors: EADDRINUSE, 503, out of memory, module not found

Most Node.js hosting problems come down to a handful of errors. This guide explains what each one means and how to fix it on cPanel hosting and on a VPS. Always start by reading the log: see Node.js logs and debugging.

Before you start

• The exact error message from stderr.log, pm2 logs or your terminal.
• SSH or File Manager access.

Error: listen EADDRINUSE (port already in use)

Error: listen EADDRINUSE: address already in use :::3000 means another process already listens on that port, often an old copy of your own app.

1. Find what holds the port:
   Copy

   sudo ss -ltnp | grep :3000

2. If it is an old PM2 process, remove it with pm2 delete NAME. Otherwise stop the process by its PID:
   Copy

   kill PID

3. Or run your app on a free port by setting PORT.

On cPanel, do not hard-code a port: Passenger supplies one. Use process.env.PORT in your code.

503 Service Unavailable on cPanel

Passenger returns 503 when your app fails to start or crashes on boot.

1. Open stderr.log in the application root.
2. Check that the Application startup file in cPanel → Software → Setup Node.js App exists and is spelled exactly right.
3. Click Run NPM Install, then Restart.
4. Make sure the Node.js version matches what your project needs.

More CloudLinux-specific causes are in CloudLinux Node.js app troubleshooting.

JavaScript heap out of memory

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory appears most often during npm run build for Next.js and other bundlers.

• On cPanel: build on your computer and upload the build output, as in Deploy Next.js on cPanel. Shared accounts have per-account memory limits.
• On a VPS: raise the heap limit for the build:
  Copy

  NODE_OPTIONS=--max-old-space-size=2048 npm run build

  and add swap if the server has little RAM:
  Copy

  sudo fallocate -l 2G /swapfile
  sudo chmod 600 /swapfile
  sudo mkswap /swapfile
  sudo swapon /swapfile

• If a running app grows until it crashes, you probably have a memory leak. Set max_memory_restart in PM2 as a safety net while you investigate.

Error: Cannot find module

Error: Cannot find module 'express' means a dependency is not installed where Node.js looks.

• Run npm install (or Run NPM Install in cPanel) in the folder that contains package.json.
• The package is in devDependencies but you installed with --omit=dev: move it to dependencies.
• For your own files (Cannot find module './Utils'), check the letter case: Linux file names are case-sensitive, Windows and macOS are not.
• Reinstall if node_modules is corrupt:
  Copy

  rm -rf node_modules
  npm ci

Other errors you may see

Next steps

• Update or switch Node.js versions
• PM2 process manager
• Node.js logs and debugging