.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
The Hermes setup wizard hangs on the line "WhatsApp bridge dependencies" for minutes. Sometimes the spinner spins, sometimes a progress message just sits frozen mid-line. People wait. Some kill it after twenty minutes. The most common cause is npm getting killed by the Linux OOM killer on a low-memory VPS without anyone seeing the kill message.
Why the install stalls
The WhatsApp bridge uses the Baileys library, which pulls in a tree of transitive Node dependencies. The full install allocates a few hundred megabytes of memory while resolving and unpacking modules. On a 1GB VPS or a WSL2 distro with no swap, npm hits the memory ceiling, the kernel kills the npm process, and the Hermes wizard sees no exit signal so it waits indefinitely.
Confirm OOM kill
tail -100 ~/.hermes/logs/install.log
dmesg | tail -50 | grep -i "killed\|oom"If dmesg shows "Out of memory: Killed process" around the time the wizard stalled, you found the cause.
Fix: add swap, then retry
Swap gives npm more virtual memory. Slower than RAM but it stops the OOM kill. We only need it for the few minutes of npm install, but you can leave it on permanently if you want.
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
free -hVerify the swap shows up in free -h. Then re-run the WhatsApp setup:
hermes gateway setup whatsappMake swap persist across reboots
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstabIf swap doesn't help: check Node version
Baileys requires Node v18 or v22 LTS. Older Node versions (or weird in-between versions) fail in ways that look like a hang.
node --version
which nodeInstall correct Node via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node --versionRetry the bridge install.
If swap and Node are fine: check disk space
The npm install temp directory needs about 500MB free during resolve.
df -h /tmp /homeBelow 1GB free, the install stalls mid-write. Clean up and retry.
What to do if dependencies install but bridge still won't start
The npm install completed but the bridge crashes immediately when Hermes tries to start it. Different failure, similar symptom.
Check the bridge log
tail -50 ~/.hermes/logs/whatsapp-bridge.logCommon bridge startup errors and fixes
- Missing module: install was partial, reinstall from scratch (see below)
- Wrong Node binary on PATH: nvm is using one Node but Hermes is calling a different one. Check
which nodematches what nvm activated. - Port 3000 already taken: see our WhatsApp bridge localhost:3000 fix
Clean reinstall of bridge deps
cd ~/.hermes/hermes-agent/scripts/whatsapp-bridge
rm -rf node_modules package-lock.json
npm install --no-audit --no-fund
hermes gateway restart whatsappSkipping WhatsApp temporarily
If the bridge install keeps failing and you need to move on, the rest of Hermes works fine without WhatsApp. You can finish the wizard, set up Telegram or Discord first and come back to WhatsApp later.
# skip WhatsApp during wizard or set up another gateway:
hermes gateway setup telegram
hermes gateway setup discordOur Telegram setup tutorial is the easiest channel to get running while you sort the WhatsApp issue.
Pre-built Docker bridge as an alternative
If the wizard install keeps failing on your setup, running Hermes (and the bridge) in Docker is a workaround. The bridge install runs inside a controlled container environment with the right Node and enough memory allocated.
Full Compose pattern in our Hermes Docker Compose tutorial.
WhatsApp ban-risk worth noting again
Before finishing the WhatsApp setup: Baileys is a reverse-engineered WhatsApp Web client. Not an official API. Meta does ban accounts that look automated. Use a dedicated number, not your personal one. Full caveats in our Hermes Baileys setup.
Memory headroom on the VPS itself
1GB VPS plans are tempting on price but you pay for it in install pain and the agent runs slower in general. 2GB is the floor for production Hermes use. On LumaDock the 2GB tier is the entry point, with higher tiers giving real headroom for Node-heavy bits. Unmetered bandwidth and no setup fees. Setup details in our Hermes Agent complete guide.
