{"record":{"id":"8ee5487a2cbd5f1e","repo":"agentscope-ai/agentscope","slug":"gateway-failed-to-list-mcps-safe-detail-status","errorCode":null,"errorMessage":"gateway failed to list MCPs: {_safe_detail(status, body)}","messagePattern":"gateway failed to list MCPs: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/agentscope/workspace/_gateway_client.py","lineNumber":529,"sourceCode":"        maintaining their upstream sessions.\n\n        Args:\n            agent_id (`str`, defaults to ``\"\"``):\n                The agent whose MCP clients to fetch.\n            session_id (`str`, defaults to ``\"\"``):\n                The session whose MCP clients to fetch.\n\n        Raises:\n            `RuntimeError`:\n                Gateway returned non-2xx.\n        \"\"\"\n        status, body = await self.exec_request(\n            \"GET\",\n            \"/mcps\",\n            params={\"agent_id\": agent_id, \"session_id\": session_id},\n        )\n        if status >= 400:\n            raise RuntimeError(\n                f\"gateway failed to list MCPs: {_safe_detail(status, body)}\",\n            )\n        specs = json.loads(body)\n        return [\n            self.make_client(\n                spec,\n                agent_id=agent_id,\n                session_id=session_id,\n                connected=True,\n            )\n            for spec in specs\n        ]\n\n    def make_client(\n        self,\n        spec: dict[str, Any],\n        *,\n        agent_id: str = \"\",","sourceCodeStart":511,"sourceCodeEnd":547,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/workspace/_gateway_client.py#L511-L547","documentation":"Raised by GatewayClient.list_mcps() when GET /mcps through the sandbox shim returns HTTP >= 400. The gateway inside the sandbox refused or failed the listing request — commonly an auth failure (bad/missing bearer token), a gateway crash, or an internal error serializing MCP specs. The message embeds the status and truncated body via _safe_detail.","triggerScenarios":"`await gateway.list_mcps(agent_id, session_id)` when the auth token configured on GatewayClient doesn't match the gateway, the gateway process crashed mid-request, or the gateway returned 500 while dumping MCP specs.","commonSituations":"Wrong auth_token after gateway restart with a regenerated token; gateway version mismatch between host shim script and in-sandbox server; port collision where 127.0.0.1:gateway_port inside the sandbox is served by a different process; gateway restarted and lost all state (still 200 usually, but 500 possible on partial init).","solutions":["Check the status/body in the message: 401/403 → fix auth_token; 500 → read gateway logs via gateway_log_path","Verify gateway liveness with `await gateway.health()`","Confirm gateway_port points at the right in-sandbox process (no port collision)","Upgrade/redeploy so the host library and in-sandbox gateway versions match"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if not await gateway.health():\n    raise RuntimeError(\"gateway unreachable\")","typeGuard":null,"tryCatchPattern":"try:\n    mcps = await gateway.list_mcps(agent_id, session_id)\nexcept RuntimeError as e:\n    logger.error(\"list_mcps failed: %s\", e)\n    mcps = []","preventionTips":["Health-check the gateway before listing","Keep auth_token in sync with the gateway configuration","Retry once with backoff during startup races"],"tags":["mcp","gateway","list","http-4xx","auth"],"backgroundTag":"mcp-gateway-request-failed","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}