{"record":{"id":"f892917dbc0cf3ca","repo":"NousResearch/hermes-agent","slug":"codex-app-server-error-code-message","errorCode":null,"errorMessage":"codex app-server error {code}: {message}","messagePattern":"codex app-server error (.+?): (.+?)","errorType":"exception","errorClass":"CodexAppServerError","httpStatus":null,"severity":"error","filePath":"agent/transports/codex_app_server.py","lineNumber":236,"sourceCode":"    ) -> dict:\n        \"\"\"Send a JSON-RPC request and block on the response. Returns `result`,\n        raises CodexAppServerError on `error`.\"\"\"\n        rid = self._take_id()\n        q: queue.Queue = queue.Queue(maxsize=1)\n        with self._pending_lock:\n            self._pending[rid] = _Pending(queue=q, method=method)\n        self._send({\"id\": rid, \"method\": method, \"params\": params or {}})\n        try:\n            msg = q.get(timeout=timeout)\n        except queue.Empty:\n            with self._pending_lock:\n                self._pending.pop(rid, None)\n            raise TimeoutError(\n                f\"codex app-server method {method!r} timed out after {timeout}s\"\n            )\n        if \"error\" in msg:\n            err = msg[\"error\"]\n            raise CodexAppServerError(\n                code=err.get(\"code\", -1),\n                message=err.get(\"message\", \"\"),\n                data=err.get(\"data\"),\n            )\n        return msg.get(\"result\", {})\n\n    def notify(self, method: str, params: Optional[dict] = None) -> None:\n        \"\"\"Send a JSON-RPC notification (no id, no response expected).\"\"\"\n        self._send({\"method\": method, \"params\": params or {}})\n\n    def respond(self, request_id: Any, result: dict) -> None:\n        \"\"\"Reply to a server-initiated request (e.g. approval prompts).\"\"\"\n        self._send({\"id\": request_id, \"result\": result})\n\n    def respond_error(\n        self, request_id: Any, code: int, message: str, data: Optional[Any] = None\n    ) -> None:\n        \"\"\"Reply to a server-initiated request with an error.\"\"\"","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/agent/transports/codex_app_server.py#L218-L254","documentation":"CodexAppServerError from CodexAppServerClient.request() (agent/transports/codex_app_server.py:236), raised when the JSON-RPC response carries an 'error' object. The exception carries the server's code (default -1 if absent), message, and optional data — it is the codex app-server rejecting the call, not a transport failure.","triggerScenarios":"Any request whose params the codex server rejects: unknown method name, invalid params shape, invalid model/config values, permission denials, or internal server errors (code -32603) such as the thread/start payload mismatch.","commonSituations":"Version skew between this client and the installed codex app-server (renamed methods/params); passing a model or cwd the server rejects; malformed params after a refactor of the session layer.","solutions":["Read the exception's .message/.code/.data — they come straight from codex and usually name the offending param.","Match the method/param names against the codex app-server version you spawn; pin or upgrade codex to a tested version.","Handle specific codes differently: -32601 unknown method strongly implies version skew; invalid-params implies a caller bug.","Log the full request params at DEBUG when surfacing this so the failing call is reproducible."],"exampleFix":"# before\nresult = client.request(method, params)\n\n# after\nfrom agent.transports.codex_app_server import CodexAppServerError\ntry:\n    result = client.request(method, params)\nexcept CodexAppServerError as exc:\n    if exc.code == -32601:\n        raise RuntimeError(f\"codex too old for {method!r}; upgrade codex\") from exc\n    raise","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"from agent.transports.codex_app_server import CodexAppServerError\n\ntry:\n    result = client.request(method, params)\nexcept CodexAppServerError as exc:\n    if exc.code == -32601:\n        raise UnsupportedCodexVersion(method) from exc\n    logger.error(\"codex rejected %s: %s (%s)\", method, exc.message, exc.code)\n    raise","preventionTips":["Pin the codex app-server version you test against.","Branch on exc.code: method-not-found means version skew, invalid-params means a caller bug.","Log request params at DEBUG when a CodexAppServerError occurs for reproducibility."],"tags":["jsonrpc","codex","protocol-error"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}