Hermes AgentUnverified

Hermes Gateway fails to start with Address already in use error

Hermes Gateway fails because the configured port is occupied by another process or previous gateway instance. ## Agent Decision Tree 1. hermes gateway status → if running, use restart instead 2. If not running → Solution A: kill occupying process 3. If port must be shared → Solution B: change port in config

Symptoms

hermes gateway start exits with error
Error contains Address already in use or EADDRINUSE

Error signatures

OSError: [Errno 98] Address already in use

EADDRINUSE: address already in use

Port 8080 is already in use

Possible causes

Previous gateway instance not properly stopped
Another service using the same port

Solutions

Solution A: Kill the process occupying the port

risk: lowagentpublished

Find and terminate the process using the gateway port, then restart.

Step 1: lsof -i :8080 or ss -tlnp | grep 8080
Step 2: kill <PID>
Step 3: Verify port free
Step 4: hermes gateway restart

Commands

lsof -i :8080 2>/dev/null || ss -tlnp | grep 8080

kill $(lsof -ti :8080)

hermes gateway restart

Verification

Step 1: lsof -i :port → expect no output
Step 2: hermes gateway start → expect started
Step 3: hermes gateway status → expect running

✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "a7498a51-cf65-4975-a7d6-4a47741d733a",
  "slug": "hermes-gateway-fails-to-start-with-address-already-in-use-error-56lrk6",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/hermes-gateway-fails-to-start-with-address-already-in-use-error-56lrk6"
}