{"record":{"id":"f2d5abeeb8f50c0b","repo":"NousResearch/hermes-agent","slug":"the-generated-proxy-yaml-has-no-management-listene","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"warning","filePath":"agent/proxy_sources/iron_proxy.py","lineNumber":936,"sourceCode":"    POSTs to ``/v1/reload`` on the loopback management listener; the daemon\n    re-reads proxy.yaml and atomically swaps the transform pipeline —\n    validation failures leave the running config untouched (HTTP 422).\n\n    Returns True on a successful reload.  Raises ``RuntimeError`` with an\n    actionable message when the daemon isn't running, the config predates\n    management-API support (no ``management`` block → restart required),\n    or the reload is rejected.\n    \"\"\"\n\n    pid = _read_pid()\n    if not pid or not _pid_alive(pid):\n        raise RuntimeError(\n            \"iron-proxy is not running — nothing to reload.  \"\n            \"Run `hermes egress start`.\"\n        )\n    mgmt = _read_management_listen_from_config()\n    if mgmt is None:\n        raise RuntimeError(\n            \"The generated proxy.yaml has no management listener (written \"\n            \"before reload support).  Re-run `hermes egress setup` and use \"\n            \"`hermes egress restart` this one time.\"\n        )\n    token = _read_management_token()\n    if not token:\n        raise RuntimeError(\n            \"management.token is missing — re-run `hermes egress setup`, \"\n            \"then `hermes egress restart`.\"\n        )\n\n    import urllib.error\n    import urllib.request\n\n    host, port = mgmt\n    req = urllib.request.Request(\n        f\"http://{host}:{port}/v1/reload\",\n        method=\"POST\",","sourceCodeStart":918,"sourceCodeEnd":954,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/agent/proxy_sources/iron_proxy.py#L918-L954","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"from pathlib import Path\nfrom agent.proxy_sources.iron_proxy import _proxy_state_dir\n\ndef config_has_management_block() -> bool:\n    import yaml\n    cfg = _proxy_state_dir() / \"proxy.yaml\"\n    if not cfg.exists():\n        return False\n    return \"management\" in (yaml.safe_load(cfg.read_text()) or {})","typeGuard":null,"tryCatchPattern":"try:\n    reload_proxy()\nexcept RuntimeError as e:\n    if \"no management listener\" in str(e):\n        # one-time migration: regenerate config + restart\n        raise","preventionTips":["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."],"tags":["migration","config","daemon","iron-proxy"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}