AgentFixboard
UnverifiedLast checked Hermes Agent#transport#setup

A2A listener cannot bind an IPv6 host and reports bind_failed

With A2A_HOST=::1 and no token, the A2A adapter logs A2A: could not bind ::1:9900 — [Errno 8] nodename nor servname provided, or not known and reports bind_failed. The platform never connects.

From GitHub

NousResearch/hermes-agent

IssuePull request

Difficulty
Easy
Time
~5 min
Steps
2
Fixed in
—
Last checked

Unverified: we could not confirm from the sources that a fix shipped. Source: PR #135309 merged. Last checked 2026-10-20.

Symptom

With A2A_HOST=::1 and no token, the A2A adapter logs A2A: could not bind ::1:9900 — [Errno 8] nodename nor servname provided, or not known and reports bind_failed. The platform never connects.

Evidence what you'll see

  • A2A_HOST=::1 is accepted by A2ASecurityContext.resolve_bind_host without a token, and A2A_HOST=:: is accepted with one.
  • The issue's direct probe is ThreadingHTTPServer(("::1", 0), BaseHTTPRequestHandler), which raises socket.gaierror on macOS and Linux.
  • The Agent Card URL is built as http://{host}:{port}/, which is not a valid URL for an IPv6 literal such as http://::1:9900/.

Why it happens

A2AAdapter.connect builds a plain ThreadingHTTPServer, whose address_family is AF_INET. getaddrinfo for an IPv6 host on that family fails. Pull request 135309 gives every IPv6 A2A_HOST an AF_INET6 server, sets IPV6_V6ONLY=0 on :: so one socket serves both families, unmaps ::ffff: peers, and brackets IPv6 literals in the Agent Card URL.

Affected versions

macOS 27.0, Python 3.14.6, Hermes main at 35272ce28b. The same ThreadingHTTPServer(("::1", 0), ...) probe fails on Linux.

Fix steps

0 of 2 done

Your check marks stay in this browser only.

How to check it worked

  • hermes gateway run with A2A_HOST=::1 logs that A2A connected, instead of bind_failed and A2A: could not bind ::1:9900.

If it still fails

  • No published release tag contains pull request 135309. Tag v0.22.2 was compared against merge 8ddf6d1234 and does not contain it.
  • Pull request 126285, which first added the bracketed Agent Card URL, was closed unmerged. The salvage is pull request 135309.

Sources and credit

Summarized in our own words from these public reports. Credit goes to their authors.

Provided as is, without warranty. Try changes in a non-production environment and back up first. Security-related steps: verify against the official docs. Terms · Request removal or attribution change

Hit an error we don't cover? Submit it