Node.js app in cPanel returns 503: the usual causes

A 503 error on an application created under “Setup Node.js App” almost always means the same thing: the server tried to start the application and it did not start, or started and fell over at once. What connects them to the server is Passenger, and whatever the application writes as it fails ends up in its log. Nearly everything is found by reading that log and running the application by hand once. This article goes in order of likelihood.

Finding the cause, step by step

1	Open the application screen under “Setup Node.js App” and check three fields: the application root, the address and the startup file. Are they right? Does the file really exist in the root, with that exact name (upper and lower case count)?

2	Read the log. The screen has a Passenger log file field. If it is empty, give it a file inside the application folder, save, restart, repeat the request that fails, and open the file. The last message is usually the cause.

3	Run the application by hand. If the account has a terminal, enter the virtual environment with the command the application screen shows at the top and run the startup file (node app.js). A syntax error, a missing module or an unset variable shows straight away on screen. Stop with Ctrl+C.

4	Fix, install and restart. After fixing, use “Run NPM Install” if the dependencies changed, and the restart button so Passenger loads everything again.

The causes, in order

Cause	What the log usually says	What to do
Wrong startup file	It cannot find the file, or the path does not exist.	Fix the field on the application screen. It is relative to the application root.
Dependencies not installed	“Cannot find module” followed by a name.	“Run NPM Install”. Do not upload the `node_modules` folder over FTP.
Node.js version does not suit the code	A “SyntaxError” or “Unexpected token” on a line that looks right.	Pick a newer version, or the one the project asks for, and reinstall the dependencies.
Missing variable or connection	A database connection error, or “undefined” where a value should be.	Set the variables on the application screen and restart. See environment variables and secrets.
The application does not stay running	It starts and ends at once, with no error.	The process has to start an HTTP server and stay up. A script that runs one task and finishes will not do.
Changes not applied	The error is the one from before you fixed it.	Restart the application.
Account limits	Out of memory or processes; or the error is 508 rather than 503.	See errors 500, 403, 404 and 508.
`.htaccess` tampered with	Passenger is no longer called for that address.	The file has a block marked by CloudLinux Passenger, created by the tool. Do not delete or edit it. If a WordPress site sits at the root of the same domain, the rules of one can catch the other.

To tell “the server” from “my code”, put a minimal application in place of yours and see whether it answers:const http = require("http");
http.createServer((req, res) => {
res.end("ok");
}).listen(process.env.PORT || 3000);If this one answers and yours does not, the problem is in the code or the dependencies. If not even this one answers, add the Passenger log to your support request.

Do not try to use ports 80 or 443, and do not depend on a fixed port number for the visitor to reach the application. Passenger is what connects the site address to the process. Opening ports on your own only brings conflicts.

A 503 also has other sources that have nothing to do with Node.js: maintenance, overload or stopped services. Error 503 and the rest of the 5xx family helps tell them apart. And if you need an always-on process, a queue or a bot, a VPS is the right place: PM2 on a VPS.

Read the log and still lost? Send us the domain, the time of the error and the last message in the log, and we will see what the server does.

Open a support ticket

Knowledgebase

Categories

Categories

Support

Finding the cause, step by step

The causes, in order

Knowledgebase

Categories

Categories

Support