Que faire si une application Node.js ne se lance pas ?

Une application Node.js qui répond 503, ou une page d'erreur à la place de votre site, se ramène presque toujours à trois causes. Passenger exécute un seul fichier puis attend qu'il ouvre un port : ce qui cloche, c'est le fichier, ou le port.

Le fichier de démarrage n'est pas le bon

Passenger n'exécute pas npm start. Il exécute le fichier que le projet désigne comme fichier de démarrage, et si ce fichier n'existe pas, rien ne démarre.

Pour un projet déployé avec Hodifly, indiquez-le dans cPanel > Hodifly > votre projet > Fichier de démarrage, ou mieux, dans le dépôt lui-même avec "startup": "dist/main.js" dans un fichier hodifly.json, appliqué à chaque déploiement. Le cas courant est celui d'une application compilée : NestJS compile vers dist/main.js, et un chemin est tout à fait valable ici. Votre application est quand même lancée depuis la racine du projet : les dossiers qui l'entourent restent accessibles.

Un piège à connaître : Passenger charge ce fichier avec require(), donc un point d'entrée en module ES (un fichier .mjs, ou un projet en "type": "module") échoue tout seul. Faites plutôt pointer le fichier de démarrage sur une petite passerelle CommonJS, server.cjs à la racine du projet :

process.env.NODE_ENV = process.env.NODE_ENV || 'production';
import('./dist/server/server.mjs').catch(e => { console.error(e); process.exit(1); });

Votre application n'appelle jamais listen()

Passenger lance votre application en se branchant sur listen(). Une application qui ne l'appelle jamais n'est pas un serveur web, et rien ne répondra. Écoutez sur le port que Passenger vous donne :

app.listen(process.env.PORT || 3000);

Un build Angular SSR est la surprise classique ici : le server.mjs généré n'écoute que s'il est le module principal, ce qu'il n'est pas sous Passenger. Retirez cette condition pour qu'il écoute toujours.

Votre application appelle listen() plusieurs fois

Avec plusieurs serveurs HTTP, Passenger ne sait pas sur lequel se brancher et abandonne. La documentation Phusion Passenger explique l'ajustement à faire.

Lisez l'erreur plutôt que de deviner

La sortie de votre application, y compris la trace de l'erreur qui l'a tuée, est écrite dans un fichier de journal sur votre compte. Pour un projet Hodifly :

~/logs/hodifly-<projet>-<branche>.log

Ouvrez-le dans cPanel > Gestionnaire de fichiers, ou en FTP. Neuf fois sur dix la raison est dans les dernières lignes : un module manquant, une variable d'environnement absente, un port déjà pris. La compilation, elle, a son propre journal : cPanel > Hodifly > votre projet > le déploiement.

Mis à jour le : 31/08/2026