Troubleshoot Node.js apps in cPanel (CloudLinux Node.js Selector)

Node.js apps on cPanel run through Passenger inside your account's CloudLinux environment. Most problems come from a wrong startup file, a fixed port, a missing build or the memory limit. This guide goes through the errors in the order you are likely to meet them.

Before you start

• An app created in cPanel → Software → Setup Node.js App (see setting up a Node.js app).
• Access to cPanel → Advanced → Terminal or SSH helps a lot.

Find the error message first

1. Open the application root in File Manager and look for stderr.log (or the log file set on the app page).
2. Read the last lines. The real error, such as Cannot find module 'express', is usually there.
3. Also check cPanel → Metrics → Errors.

Common problems and fixes

503 Service Unavailable or "Incomplete response received"

• The startup file crashed on start. Read stderr.log.
• The app listens on a fixed port. Use process.env.PORT.
• The startup file name on the app page does not match the real file.

Cannot find module

• Dependencies are not installed. Click Run NPM Install.
• You uploaded node_modules from Windows or macOS. Delete it and reinstall on the server.
• The package is a dev dependency but the app runs in production mode. Move it to dependencies.

npm install fails or is killed

• Large installs can exceed the account's memory or process limit. Install from the Terminal inside the virtual environment, one step at a time, and remove unused packages.
• Packages that compile native code (such as sharp or bcrypt) may need a prebuilt binary. Use bcryptjs instead of bcrypt, or check the package's prebuilt options.

Wrong Node.js version

In the Terminal, run commands only after activating the app's environment with the source …/activate line shown at the top of the app page. Without it, node -v may show another version.

ES module errors (import/require)

Passenger loads the startup file with require. If your app uses ES modules ("type": "module"), create a small CommonJS startup file that imports your ES module with dynamic import().

Changes do not appear

Click Restart on the app page after every code or environment change. Also purge LiteSpeed or CDN caches if the app sits behind them.

App stops after a while

Passenger stops idle apps and starts them on the next request; the first request is slower. For apps that must always run background jobs, consider a VPS.

Check resource limits

If errors mention memory or the app dies under load, open cPanel → Metrics → Resource Usage and look for memory or process faults (see reading Resource Usage). Reduce memory use, or upgrade your plan.

Still stuck?

Open a support ticket with the app name, the Node.js version and the last lines of stderr.log.

Frequently asked questions

Does the app need its own domain?

No. It can run on a subdomain or a path such as /api on an existing domain, set as the Application URL.

Can I use Yarn or pnpm?

npm is supported directly. Yarn or pnpm can work from the Terminal inside the virtual environment, but keep a package-lock.json for the Run NPM Install button.