.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
You configure the Baileys-based WhatsApp bridge in Hermes Agent, send a test message and the gateway log shows:
WhatsApp send failed: Cannot connect to host localhost:3000 ssl:default
[Connect call failed ('127.0.0.1', 3000)]This is the most-reported WhatsApp bug in the upstream Hermes repo. Hermes is trying to forward to the WhatsApp bridge service on port 3000 and the bridge isn't listening. Four common causes, each with a quick check.
Cause 1: WhatsApp bridge process is not running
The bridge is a separate Node service that Hermes installs under ~/.hermes/hermes-agent/scripts/whatsapp-bridge/. It runs independently from the gateway. If it crashed or never started, no port 3000.
Check if it's running
ps aux | grep whatsapp-bridge
hermes gateway status whatsappRestart the bridge
hermes gateway restart whatsappWatch the bridge log
tail -f ~/.hermes/logs/whatsapp-bridge.logYou want a line saying the bridge is listening on port 3000. If the log shows crashes, see cause 3 below.
Cause 2: Port 3000 is taken by something else
If another process on the box owns port 3000 (a stray Node app, a leftover dev server, an old bridge from a previous Hermes install), the new bridge can't bind and quietly dies.
Check the port
ss -tlnp | grep :3000
# or
netstat -tlnp 2>/dev/null | grep :3000Either kill the conflicting process or change the bridge port
hermes gateway set whatsapp --bridge-port 3100
hermes gateway restart whatsappThe agent updates its outbound URL automatically. Just don't pick a port that's also in use.
Cause 3: Bridge dependencies didn't install correctly
The bridge's Node modules sit under ~/.hermes/hermes-agent/scripts/whatsapp-bridge/node_modules/. If the original install was interrupted (low memory on a small VPS, network blip mid-npm-install, user Ctrl-C'd because they thought it had hung), modules are partial. Bridge crashes on start with errors like:
Error: Cannot find package '@whiskeysockets/baileys/index.js' imported from
/root/.hermes/hermes-agent/scripts/whatsapp-bridge/bridge.jsReinstall bridge dependencies
cd ~/.hermes/hermes-agent/scripts/whatsapp-bridge
rm -rf node_modules package-lock.json
npm install
hermes gateway restart whatsappAdd swap if you're on a small VPS
On under 2GB of RAM the npm install gets killed by the OOM killer mid-resolve. Give the install more virtual memory:
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfileThen re-run npm install. Full coverage of the dependency-install issue in our WhatsApp bridge dependencies stuck guide.
Cause 4: Hermes points at wrong URL
If the bridge is running on 3000 and accepting connections, but Hermes is dialing 3001, or 127.0.0.1 vs localhost vs an interface IP, the connect fails. Common after Hermes upgrades where the default port changed and your config didn't update.
hermes gateway config show | grep -i whatsapp
ss -tlnp | grep :3000If the URL Hermes uses for the bridge doesn't match the bridge's bind address and port, reset:
hermes gateway set whatsapp --bridge-url http://127.0.0.1:3000
hermes gateway restart whatsappDocker complicates localhost
Inside a container, localhost means the container itself, not the host. If your bridge runs on the host and Hermes runs in a container, http://localhost:3000 is empty inside the container.
Two fixes
Option A: run the bridge inside the same container as Hermes. They share loopback.
Option B: run the bridge on the host, and from inside the container use:
host.docker.internal:3000on Mac and Windows Docker Desktophttp://172.17.0.1:3000on Linux (the default docker bridge IP)
Full compose pattern in our Hermes Agent Docker Compose tutorial.
jidDecode 500 error variant
The bridge is up, the connection succeeds, but sending fails with:
WhatsApp bridge error (500): {"error":"Cannot destructure property 'user' of
'jidDecode(...)' as it is undefined."}The message target is malformed. Baileys expects WhatsApp JIDs in a specific format. Common mistake: keeping the + sign in the international number.
Correct number format
- Correct:
447700900000 - Wrong:
+447700900000 - Wrong:
07700900000
Country code plus the rest of the number as one string of digits, no plus, no spaces, no leading zero.
Same format applies to the allowlist:
hermes gateway allowlist add whatsapp 447700900000WhatsApp ban-risk reminder
The Baileys library pretends to be WhatsApp Web. Meta does periodically ban accounts that look like automation. Don't put your personal number on the bot. Get a dedicated number (SIM, eSIM, number-rental service). Full caveats in our Hermes WhatsApp Baileys setup guide.
What about WhatsApp Business API
If Baileys ban-risk is unacceptable (you're handling customer support, you need WhatsApp Business semantics, you're at scale), the official WhatsApp Business API is the right path. Setup is heavier but the account doesn't get banned for legitimate automation. Hermes supports both. The Business API webhook setup is its own topic; the bridge fixes here only apply to Baileys.
The "MEDIA: leaked into chat" upstream bug
Separate issue worth knowing: a newer bug where internal directives like MEDIA:/home/agent/workspace/file.docx appear in chat messages because the gateway didn't strip them before sending. Tracked in the Hermes issue tracker. Fix is to upgrade Hermes once the patch lands. Until then, avoid prompts that ask the agent to deliver files through WhatsApp.
What to do after the bridge works
- Configure the allowlist properly (don't run open mode in production)
- Enable voice-note transcription if you want voice-to-text
- Add monitoring so a bridge crash at 3am doesn't go unnoticed
First two are in the full Baileys setup. Monitoring fits with the broader gateway pattern in our systemd setup tutorial.
WhatsApp bridge on a LumaDock VPS
The Hermes Agent template on LumaDock has enough memory headroom (2GB minimum on entry plans, more on higher tiers) for the npm install to finish first time without OOM kills. Unmetered bandwidth and no setup fees. Full setup in our Hermes Agent complete guide.
