Issue Station
Sign In
Tools hereToolbox

hermes - 💡(How to fix) Fix WhatsApp bridge hardcodes port 3000, conflicts with local dev servers

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

The WhatsApp bridge (scripts/whatsapp-bridge/bridge.js) defaults to port 3000, which conflicts with common dev servers (Next.js, Vite, CRA, etc.) that also default to 3000.

Error Message

  • npm run dev (Next.js / Vite / etc.) silently fails with: Error: listen EADDRINUSE: address already in use 0.0.0.0:3000
  • Problem is completely opaque — user sees only the dev server error, never guesses Hermes WhatsApp bridge is the culprit

Root Cause

gateway/platforms/whatsapp.py line 253:

self._bridge_port: int = config.extra.get("bridge_port", 3000)

The bridge binds to 0.0.0.0:3000 by default. Hermes Gateway auto-starts this bridge at launch, so any co-located dev server trying to bind port 3000 fails with EADDRINUSE.

Fix Action

Workaround

Add to ~/.hermes/config.yaml:

whatsapp:
  bridge_port: 3099

Code Example

self._bridge_port: int = config.extra.get("bridge_port", 3000)

---

whatsapp:
  bridge_port: 3099
RAW_BUFFERClick to expand / collapse

Bug Report

Summary

The WhatsApp bridge (scripts/whatsapp-bridge/bridge.js) defaults to port 3000, which conflicts with common dev servers (Next.js, Vite, CRA, etc.) that also default to 3000.

Root Cause

gateway/platforms/whatsapp.py line 253:

self._bridge_port: int = config.extra.get("bridge_port", 3000)

The bridge binds to 0.0.0.0:3000 by default. Hermes Gateway auto-starts this bridge at launch, so any co-located dev server trying to bind port 3000 fails with EADDRINUSE.

Impact

  • npm run dev (Next.js / Vite / etc.) silently fails with: Error: listen EADDRINUSE: address already in use 0.0.0.0:3000
  • Problem is completely opaque — user sees only the dev server error, never guesses Hermes WhatsApp bridge is the culprit
  • Killing the port with fuser -k 3000/tcp also kills the WhatsApp bridge, which restarts and re-occupies port 3000
  • Makes the dev server appear unstable / randomly dying

Suggested Fix

Change the default port to something that does not conflict with standard dev tooling:

  • Option A: Change default from 3000 to 3099, 3500, or 53000
  • Option B: Document in config.yaml template that bridge_port should be customized

Common dev server defaults that conflict: 3000 (Next.js/Express), 3001 (CRA), 5173 (Vite), 4200 (Angular)

Workaround

Add to ~/.hermes/config.yaml:

whatsapp:
  bridge_port: 3099

Environment

  • OS: Linux Ubuntu 22.04
  • Hermes Gateway auto-starts WhatsApp bridge on launch
  • WhatsApp bridge PID confirmed occupying port 3000, blocking Next.js dev server

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#conversation history#tool integration#LLM response#prompt template#agent execution

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

hermes - 💡(How to fix) Fix WhatsApp bridge hardcodes port 3000, conflicts with local dev servers