Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PM2 refuses to start a Bun app because it cannot find bun

ErrorInterpreter bun is NOT AVAILABLE in PATH

Short 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.

  • Applies to PM2 5, Bun 1.x, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/bun
  2. 2Match what you see, then jump to its fix

    1. 1which bun prints nothing and ~/.bun/bin/bun does not existBun is not installed for the user that runs PM2Fix
    2. 2ls ~/.bun/bin/bun works but bun alone gives command not foundBun is installed but ~/.bun/bin is not on PATHFix
    3. 3bun 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

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/bin

2Fix

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 | bash

3Verify

Open a new terminal and print the version.

bun --version

Confirmed by bun.sh

Did this fix it?

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 bun

2Fix

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-app

3Verify

PM2 lists the app as online.

pm2 status

Confirmed by bun.sh

Did this fix it?

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.js

2Fix

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 save

3Verify

Restart the process and confirm it stays online.

pm2 restart my-app
pm2 status

Confirmed by pm2.keymetrics.io

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.