Quick answer
PM2 is a process manager for Node.js: it starts your app in the background, restarts it when it crashes, and keeps it running after you log out. This post runs a small order-status API under PM2 and shows what happens when the same app is started twice on the same port. It fits a small API on one server, not a platform that already manages processes.
The night the API went quiet
You deploy a small Node API, start it, and it works. Then you close the terminal, and the API dies with it. Or the app throws an uncaught error at 3 a.m., and nobody notices until a customer reports a blank page. The first fix that comes to mind is a bigger server, but it is usually neither. What the app needs is a watcher: a process that starts it, keeps it running after you log out, and brings it back when it crashes. That watcher is what this post sets up.
What I would check before using it
My first check is whether the app has to survive on its own. A script I run by hand does not need a process manager. An API that customers hit does, because a crash at 3 a.m. should fix itself. If nobody depends on the app staying up, PM2 is overhead.
My second check is how the app runs today. If it only runs while my terminal is open, every logout kills it. PM2 fixes exactly that: it detaches the app from the terminal and restarts it on a crash. That is the whole pitch.
My third check is how many copies I need. One copy is simple: one process, one port. Several copies mean cluster mode, where PM2 shares the port between workers. The demo stays in fork mode with one worker.
My fourth check is what happens when the machine itself restarts. PM2 does not survive a reboot on its own: pm2 startup brings PM2 back at boot, and pm2 save records which apps to bring back. Skip either step and the API stays down after the first reboot.
My verdict, as judgement: adopt PM2 for a Node.js API on a single server you control, where the alternative is a terminal window and hope. Skip it when a platform already manages your processes. The recommendation flips when the app outgrows one machine, because then the problem is spreading load.
One order API, kept alive by PM2
The example is a tiny order-status API for a small online shop in Karachi, built with the Node.js http module. It answers GET /orders/PK-1042 with the order as JSON, and returns a 404 for an unknown order. Three orders live in the data: Ayesha's shipped PK-1042, Bilal's delivered PK-1038, and Hina's cancelled PK-1045. It follows the Build Your First REST API With Node.js and Express post, without the framework. Here is the server:
// Tiny order-status API for the PM2 demo. Built-in http only, no dependencies.
const http = require("http");
const ORDERS = {
"PK-1042": { order_id: "PK-1042", customer: "Ayesha", items: ["kurta", "dupatta"], total: 12400, status: "shipped", expected: "18 Nov 2026" },
"PK-1038": { order_id: "PK-1038", customer: "Bilal", items: ["sneakers"], total: 7800, status: "delivered", expected: "14 Nov 2026" },
"PK-1045": { order_id: "PK-1045", customer: "Hina", items: ["handbag", "wallet"], total: 15300, status: "cancelled", expected: "17 Nov 2026" }
};
const server = http.createServer((req, res) => {
const match = req.url.match(/^\/orders\/([A-Za-z0-9-]+)$/);
if (req.method === "GET" && match && ORDERS[match[1]]) {
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify(ORDERS[match[1]]));
return;
}
res.writeHead(404, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "order not found" }));
});
const PORT = 3000;
server.listen(PORT, () => {
console.log(`Order API listening on http://localhost:${PORT}`);
});
First I ran it directly with node server.js to check it before handing it to PM2. It printed "Order API listening on http://localhost:3000", and curl returned Ayesha's order and a 404 for an unknown one. Only then did I install PM2 with npm install pm2 and start the app under it:
$ pm2 start server.js --name order-api
[PM2] Starting server.js in fork_mode (1 instance)
[PM2] Done.
$ pm2 list
id | name | mode | pid | uptime | restarts | status
0 | order-api | fork | 6488 | 0s | 0 | online
$ curl http://localhost:3000/orders/PK-1042
{"order_id":"PK-1042","customer":"Ayesha","items":["kurta","dupatta"],"total":12400,"status":"shipped","expected":"18 Nov 2026"}
$ curl http://localhost:3000/orders/PK-1038
{"order_id":"PK-1038","customer":"Bilal","items":["sneakers"],"total":7800,"status":"delivered","expected":"14 Nov 2026"}
PM2 lists the app as online with 0 restarts. For a fuller framework, the Express Explained: Node's Minimal Web Framework Guide post is the usual next step, and Fastify: A Fast Node API Without the Ceremony is the faster one.
The thing that went wrong came next: I started the same server a second time as order-api-copy, on the same port:
$ pm2 start server.js --name order-api-copy
$ pm2 list
id | name | mode | pid | uptime | restarts | status
0 | order-api | fork | 6488 | 17s | 0 | online
1 | order-api-copy | fork | 0 | 0 | 15 | errored
$ pm2 logs order-api-copy --lines 12 --nostream
Error: listen EADDRINUSE: address already in use :::3000
code: 'EADDRINUSE', errno: -98, syscall: 'listen', port: 3000
The copy crashed on startup because port 3000 was already taken, and PM2 restarted it 15 times in about six seconds before it settled on errored. The fix is to delete the duplicate: a port conflict never fixes itself:
$ pm2 delete order-api-copy
[PM2] [order-api-copy](1) done
$ curl http://localhost:3000/orders/PK-1042
{"order_id":"PK-1042","customer":"Ayesha","items":["kurta","dupatta"],"total":12400,"status":"shipped","expected":"18 Nov 2026"}
$ pm2 restart order-api
[PM2] [order-api](0) done
$ curl http://localhost:3000/orders/PK-1045
{"order_id":"PK-1045","customer":"Hina","items":["handbag","wallet"],"total":15300,"status":"cancelled","expected":"17 Nov 2026"}
The original kept answering through all of it. One process per port is the rule. After the demo I stopped everything with pm2 delete order-api and pm2 kill, and curl confirmed the port was free.
Common mistakes and how to fix them
First, starting the same app twice on one port. The symptom is a process stuck on errored with a fast-growing restart count, and logs full of Error: listen EADDRINUSE: address already in use :::3000. The fix is pm2 delete for the duplicate, then one process per port, or cluster mode with -i 2 to share it.
Second, starting the app with no name. The symptom is a pm2 list full of entries called server, with no way to tell which is which. The fix is pm2 start server.js --name order-api, so every command names the app.
Third, assuming PM2 survives a reboot. The symptom is an API that works for weeks, then stays down after a server restart. The fix is pm2 startup, then pm2 save, and a test reboot before you depend on it.
Fourth, deploying new code without restarting the process. The symptom is a fix that works on your machine and never appears on the server, because PM2 is still running the old file. The fix is pm2 restart order-api after every deploy, then curl to check the new code is live.
Frequently Asked Questions
Is PM2 free to use? Yes. PM2 is free and open source, and running it on your own server costs nothing. Paid features exist on the Keymetrics platform, but the process manager needs no account.
Do I still need NGINX or Docker if I use PM2? PM2 is not a replacement for either. It keeps your Node process alive; it does not terminate TLS. That is the job of NGINX Explained: The Server in Front of Your Server. When the app outgrows one server, Docker Explained: Containers Without the Confusion is the next step.
What is the difference between fork mode and cluster mode? Fork mode runs one process, as this demo used. Cluster mode starts several workers that share one port, using pm2 start server.js -i max. Cluster mode fits a busy API; fork mode fits everything else.
Will PM2 restart my app when the server reboots? Only if you set it up: run pm2 startup once, then pm2 save. Without both, a reboot leaves the API down, so test it with a real reboot first.
What to remember
- Name every app with --name, so pm2 list stays readable.
- One process per port, or use cluster mode to share it.
- Read pm2 logs first; the error is usually named there.
- Run pm2 startup and pm2 save, or a reboot leaves the API down.
- Restart after every deploy, then curl to prove the new code is live.
Where this leaves you
PM2 answers one question: who watches the app when you are not looking? The demo answered it: the API started, stayed online, answered real orders, and survived a duplicate start that crashed on a port conflict. That is the whole job for a small Node API on one server. Start with one named process, check pm2 list and pm2 logs after every deploy, and set up pm2 startup before the first reboot. If the app grows past one machine, reach for containers, not more PM2.
Further reading
- PM2 quick start, official docs, https://pm2.keymetrics.io/docs/usage/quick-start/
- PM2 documentation, https://pm2.keymetrics.io/docs/introduction/overview/
- Node.js HTTP module docs, https://nodejs.org/api/http.html
- Build Your First REST API With Node.js and Express, https://practicaldevblog.blogspot.com/2026/10/build-your-first-rest-api-with-nodejs.html
- Express Explained: Node's Minimal Web Framework Guide, https://practicaldevblog.blogspot.com/2026/10/express-explained-nodes-minimal-web.html
- Fastify: A Fast Node API Without the Ceremony, https://practicaldevblog.blogspot.com/2026/11/fastify-fast-node-api-without-ceremony.html
- NGINX Explained: The Server in Front of Your Server, https://practicaldevblog.blogspot.com/2026/11/nginx-explained-server-in-front-of-your.html
- Docker Explained: Containers Without the Confusion, https://practicaldevblog.blogspot.com/2026/10/docker-explained-containers-without.html
Waqas Shahid is a software engineer from Karachi with more than 12 years of experience, including 6+ years in engineering leadership. He writes The Practical Developer.
Top comments (0)