cPanel's Setup Node.js App runs your app through Phusion Passenger. When the app fails to start or crashes, visitors see 503 Service Unavailable or a Passenger error page. The cause is almost always in the app configuration and is visible in its logs.
Before you start
- Access to cPanel → Software → Setup Node.js App and, ideally, SSH or Terminal.
- The app's entry file name (e.g.
app.jsorserver.js).
Check the app settings
- Open Setup Node.js App and edit the application.
- Application root: the folder containing
package.json. - Application startup file: the exact file that starts the server, relative to the root.
- Node.js version: one your app supports.
- Application mode: Production.
Install dependencies
Click Run NPM Install on the app page, or over SSH enter the app's virtual environment (the command is shown at the top of the app page) and run:
npm install --omit=devcPanel stores node_modules as a symlink into the app's virtual environment; do not upload your own node_modules folder, which conflicts with it.
Do not hard-code the port
Passenger tells your app where to listen. Use the environment port with a fallback:
const port = process.env.PORT || 3000;
app.listen(port);Listening on a fixed port such as 3000 or 8080, or binding to a specific IP, prevents Passenger from connecting and results in a 503.
Read the logs
- Enable or check the app's log path if your cPanel version offers it; many setups write
stderr.login the application root. - The domain's error log under cPanel → Metrics → Errors.
- Run the app by hand in the virtual environment to see startup errors directly:
node app.js.
Common errors
| Log message | Fix |
|---|---|
Cannot find module 'express' | Run NPM Install; check package.json lists the module |
SyntaxError: Cannot use import statement outside a module | Add "type": "module" to package.json or use require() |
EADDRINUSE | Remove the hard-coded port; use process.env.PORT |
Unsupported engine / syntax errors in modern code | Select a newer Node.js version |
| App starts, then stops under load | CloudLinux limits reached; see below |
Environment variables
Add secrets and settings in the app's Environment variables section, then restart. A missing variable (database URL, API key) commonly makes the app throw at startup.
Restart and test
Click Restart after each change (or touch tmp/restart.txt in the app root). Then load the URL.
Resource limits
Accounts on CloudLinux have memory, process and entry-process limits. Builds (npm run build for Next.js, for example) or memory-hungry apps can hit them. Check cPanel → Metrics → Resource Usage for faults; build locally and upload the output if the build fails on the server.
Troubleshooting
- 503 only after some time idle: Passenger stops idle apps and starts them on the next request; a slow startup can briefly show errors. Optimise startup work.
- Static site works, API routes 404: the app URL or base path in the app settings does not match your routes.
- WebSockets do not connect: Passenger on shared hosting may not support them; use a VPS for real-time apps.
Node.js on cPanel FAQ
Can I use PM2 on cPanel?
No, Passenger manages the process; PM2 is for VPS setups.
Can I run Next.js on cPanel?
Yes, with a custom server file as the startup file, or as a static export. See the Next.js on cPanel guide.
When should I move to a VPS?
When you need WebSockets, background workers, more memory, or full control over the Node.js process.