PM2 : dépannage

Procédure de diagnostic

pm2 list                                  # état et compteur de redémarrages
pm2 show api                              # détails, chemins, dernière erreur
pm2 logs api --err --lines 50 --nostream  # erreurs récentes
pm2 logs api --lines 50 --nostream
sudo ss -tlnp | grep -E ':3000|node'      # ports en écoute
systemctl status pm2-appli                # service de démarrage automatique

Lancer l’application à la main (hors PM2) reproduit la plupart des erreurs de démarrage :

pm2 stop api
cd /srv/monapp && node src/serveur.js

Problèmes fréquents

Symptôme	Cause et solution
Statut `errored`	Plantage au démarrage : `pm2 logs api --err` ; erreur de code, variable manquante, base inaccessible
Compteur `↺` qui monte	Redémarrage en boucle : même cause ; limiter avec `--max-restarts` et `--min-uptime`
`Error: listen EADDRINUSE :::3000`	Port occupé : `sudo ss -tlnp \| grep 3000`, arrêter l’autre processus ou doublon PM2 (`pm2 list`)
`Cannot find module`	`npm ci` oublié ou mauvais `cwd` : vérifier `pm2 show api`
`Script not found`	Chemin ou `cwd` incorrect
Application « online » mais ne répond pas	Boucle bloquante, mauvaise adresse d’écoute : tester `curl http://127.0.0.1:3000/`
Variables d’environnement anciennes	`pm2 restart api --update-env` puis `pm2 save`
Applications absentes après redémarrage	`pm2 save` oublié ou `pm2 startup` non configuré : voir Démarrage automatique
`pm2: command not found` dans un service ou une tâche	`PATH` sans Node.js : utiliser le chemin complet de `pm2`
`[PM2][ERROR] Permission denied`	Mauvais utilisateur : l’état de PM2 est propre à chaque utilisateur (`~/.pm2`)
Mémoire qui grimpe	Fuite : `--max-memory-restart` en attendant la correction, profiler l’application
`ENOSPC` / disque plein	Journaux volumineux : `pm2 flush`, `pm2-logrotate`
Interface web ou module `pm2 plus` demandé	Service cloud facultatif : inutile pour un usage local

Le démon PM2 est bloqué

pm2 ping
pm2 kill                  # arrête le démon ET les applications
pm2 resurrect             # relance les applications de la dernière sauvegarde

L’application redémarre sans cesse

Lire l’erreur : pm2 logs api --err --lines 100 --nostream.
Arrêter la boucle pour travailler : pm2 stop api.
Lancer l’application à la main avec les mêmes variables d’environnement.
Corriger, puis pm2 start api ou pm2 reload api.
pm2 reset api pour remettre le compteur à zéro.

Fuites de mémoire et processus lents

pm2 monit
pm2 show api | grep -iE "memory|cpu|uptime|restarts"
node --inspect src/serveur.js            # profilage avec les outils de développement de Node.js

Un redémarrage planifié (cron_restart) ou limité par la mémoire masque le problème sans le résoudre.

Réinitialiser PM2

pm2 delete all
pm2 save --force
pm2 kill
rm -rf ~/.pm2/logs/*
pm2 start ecosystem.config.cjs --env production
pm2 save

Après une mise à jour de Node.js ou d’Ubuntu

npm install -g pm2@latest
pm2 update
pm2 unstartup systemd
pm2 startup systemd       # puis la commande sudo affichée
pm2 save

Reconstruire aussi les modules natifs de l’application (npm rebuild ou npm ci).

Ubuntu 24.04 et 26.04 : différences à connaître

Les diagnostics sont identiques sur les deux versions. Après une montée de version d’Ubuntu ou de Node.js, refaire pm2 startup et pm2 save.

Pour aller plus loin

Dépannage de PM2
Retour : Installation

Dans la même rubrique