NousResearch/hermes-agent · warning · RuntimeError

The generated proxy.yaml has no management listener (written

Error message

The generated proxy.yaml has no management listener (written before reload support).  Re-run `hermes egress setup` and use `hermes egress restart` this one time.

What it means

reload_proxy() requires a `management` block in the generated proxy.yaml (listen host/port for the loopback admin API). Configs written by older Hermes versions predate that block, so _read_management_listen_from_config() returns None and reload cannot proceed — the daemon must be restarted once under a fresh config to gain the management listener. This is a one-time migration step, signposted in the message.

Source

Thrown at agent/proxy_sources/iron_proxy.py:936

    POSTs to ``/v1/reload`` on the loopback management listener; the daemon
    re-reads proxy.yaml and atomically swaps the transform pipeline —
    validation failures leave the running config untouched (HTTP 422).

    Returns True on a successful reload.  Raises ``RuntimeError`` with an
    actionable message when the daemon isn't running, the config predates
    management-API support (no ``management`` block → restart required),
    or the reload is rejected.
    """

    pid = _read_pid()
    if not pid or not _pid_alive(pid):
        raise RuntimeError(
            "iron-proxy is not running — nothing to reload.  "
            "Run `hermes egress start`."
        )
    mgmt = _read_management_listen_from_config()
    if mgmt is None:
        raise RuntimeError(
            "The generated proxy.yaml has no management listener (written "
            "before reload support).  Re-run `hermes egress setup` and use "
            "`hermes egress restart` this one time."
        )
    token = _read_management_token()
    if not token:
        raise RuntimeError(
            "management.token is missing — re-run `hermes egress setup`, "
            "then `hermes egress restart`."
        )

    import urllib.error
    import urllib.request

    host, port = mgmt
    req = urllib.request.Request(
        f"http://{host}:{port}/v1/reload",
        method="POST",

View on GitHub (pinned to c896c09c42)

Solutions

Run `hermes egress setup` to regenerate proxy.yaml with the management block.
Then run `hermes egress restart` once (this single restart is required — reload can't bootstrap a listener that isn't running).
After that, `hermes egress reload` works normally.

Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
from agent.proxy_sources.iron_proxy import _proxy_state_dir

def config_has_management_block() -> bool:
    import yaml
    cfg = _proxy_state_dir() / "proxy.yaml"
    if not cfg.exists():
        return False
    return "management" in (yaml.safe_load(cfg.read_text()) or {})

Try / catch

try:
    reload_proxy()
except RuntimeError as e:
    if "no management listener" in str(e):
        # one-time migration: regenerate config + restart
        raise

Prevention

After upgrading Hermes on a host, run `hermes egress setup` + `restart` once before relying on reload.
Include a reload smoke-test in post-upgrade verification.

When it happens

Trigger: Calling reload_proxy() / `hermes egress reload` on a machine whose proxy.yaml was generated by a Hermes version from before reload support: the file exists and the daemon may even be running, but there is no management listener to POST to.

Common situations: Upgrading Hermes (or checking out a newer version) on a long-lived host where `hermes egress setup` was last run months ago; CI machines with cached proxy state.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/f2d5abeeb8f50c0b. Report an issue: GitHub.