PM2 refuses to start a Bun app because it cannot find bun
Interpreter bun is NOT AVAILABLE in PATHShort answer
PM2 looks for the interpreter named in your start command in the PATH of the PM2 process, not in your current shell. Bun installs into ~/.bun/bin, which is often missing from that PATH. Check that bun runs in your shell, then add its folder to PATH or give PM2 the absolute path in the interpreter field.
Fix it fast
1Find out which cause you have
Ask the same user that runs PM2 where bun is. If this prints nothing, bun is not installed for that user or not on its PATH.
which bun ls ~/.bun/bin/bun2Match what you see, then jump to its fix
- 1
which bun prints nothing and ~/.bun/bin/bun does not existBun is not installed for the user that runs PM2Fix - 2
ls ~/.bun/bin/bun works but bun alone gives command not foundBun is installed but ~/.bun/bin is not on PATHFix - 3
bun works in your shell but PM2 still reports it missing, or the error returns when PM2 is started another wayPoint PM2 at the binary with an absolute pathFix
- 1
What does the error look like?
Interpreter bun is NOT AVAILABLE in PATH
Cause 1 of 3
Bun is not installed for the user that runs PM2
1Check
The Bun installer writes into the home folder of the user who ran it, in ~/.bun/bin. If you installed it as another user, or never installed it on this server, PM2 has nothing to find.
whoami
ls -l ~/.bun/bin2Fix
Install Bun as the same user that runs PM2. On Linux the installer needs unzip.
sudo apt install unzip
curl -fsSL https://bun.com/install | bash3Verify
Open a new terminal and print the version.
bun --versionConfirmed by bun.sh
Cause 2 of 3
Bun is installed but ~/.bun/bin is not on PATH
1Check
Look at the PATH of your shell. The Bun docs tell you to add its bin folder to the shell config when the command is not found.
echo "$PATH" | tr ":" "\n" | grep bun2Fix
Add the two lines from the Bun docs to ~/.bashrc (or ~/.zshrc for zsh), reload the file, then start the app again from that shell.
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
source ~/.bashrc
pm2 start index.ts --interpreter bun --name my-app3Verify
PM2 lists the app as online.
pm2 statusConfirmed by bun.sh
Cause 3 of 3
Point PM2 at the binary with an absolute path
1Check
The PM2 docs describe the interpreter option as an absolute path, and the startup command that revives your apps after a reboot passes a PATH explicitly. A path written in the config does not depend on either.
grep -n interpreter ecosystem.config.js2Fix
Set the interpreter in the ecosystem file to the full path of the Bun binary (replace the user name), then start from that file and save the list.
// ecosystem.config.js
module.exports = {
apps: [{
name: 'my-app',
script: 'index.ts',
interpreter: '/home/deploy/.bun/bin/bun',
}],
};
# then
pm2 start ecosystem.config.js
pm2 save3Verify
Restart the process and confirm it stays online.
pm2 restart my-app
pm2 statusConfirmed by pm2.keymetrics.io
How do I stop it coming back?
- Install Bun as the same service user that runs PM2, not as root or a personal account.
- Write the absolute interpreter path in ecosystem.config.js so the app does not depend on a shell profile.
- Run pm2 save after changing the process list so a reboot brings back the same setup.
- Run pm2 unstartup and then pm2 startup again after you upgrade Node.js, as the PM2 docs advise.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
Node.js cannot start because the port is already taken
Error: listen EADDRINUSE: address already in use 127.0.0.1:8080
EADDRINUSE means another socket already listens on that port, so Node's listen() was refused.
4 causes, each with a fixBack end
process.env.NODE_ENV is undefined in a Node.js app
console.log(process.env.NODE_ENV) prints undefined
Node.js does not set NODE_ENV for you.
5 causes, each with a fixBack end
PM2 does not restart my Node.js app after it crashes
status stopped in pm2 list
PM2 restarts a crashed process on its own, so a process that stays down has a reason.
3 causes, each with a fixBack end
PM2 says the ecosystem file is malformated and refuses to start
Error [ERR_REQUIRE_ASYNC_MODULE]
PM2 prints 'malformated' whenever loading the config file throws.
3 causes, each with a fixBack end
Loading a .env file into a PM2 ecosystem config fails or gives undefined values
[PM2][ERROR] File ecosystem.config.js malformated
PM2 only passes the env block of the config to your app.
4 causes, each with a fixBack end
PM2 keeps the old environment variables after restart --update-env
the app still prints the old value after pm2 restart
A plain pm2 restart reuses the environment stored at first start.
4 causes, each with a fix