{"record":{"id":"fb1bde8d3b48dccd","repo":"agentscope-ai/agentscope","slug":"gateway-request-failed-env-get-error-unknown","errorCode":null,"errorMessage":"gateway request failed: {env.get('error', 'unknown error')}","messagePattern":"gateway request failed: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"src/agentscope/workspace/_gateway_client.py","lineNumber":685,"sourceCode":"                        pass\n\n            if result.exit_code != 0:\n                raise RuntimeError(\n                    f\"gateway shim exited with {result.exit_code}: \"\n                    f\"{result.stderr.decode(errors='replace')[:500]}\",\n                )\n\n            try:\n                env = json.loads(result.stdout)\n            except Exception as e:\n                raise RuntimeError(\n                    \"gateway shim produced non-JSON stdout: \"\n                    f\"{result.stdout[:200]!r}\",\n                ) from e\n\n            status = int(env[\"status\"])\n            if status == -1:\n                raise RuntimeError(\n                    \"gateway request failed: \"\n                    f\"{env.get('error', 'unknown error')}\",\n                )\n\n            if \"body_file\" in env:\n                spilled = env[\"body_file\"]\n                body_bytes = await self.backend.read_file(spilled)\n                try:\n                    await self.backend.delete_path(spilled)\n                except Exception:\n                    pass\n            else:\n                body_bytes = base64.b64decode(env.get(\"body\", \"\"))\n\n            return status, body_bytes\n        except Exception as exc:\n            # ``/health`` never triggers diagnosis — otherwise a dead\n            # gateway would recursively probe itself.","sourceCodeStart":667,"sourceCodeEnd":703,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/workspace/_gateway_client.py#L667-L703","documentation":"Raised by GatewayClient.exec_request() when the shim successfully ran and reported a transport-level failure: the JSON envelope carries status == -1 with an 'error' field. This means the shim could not complete the HTTP request to http://127.0.0.1:{gateway_port}{path} inside the sandbox — connection refused, timeout, DNS, etc. It is distinct from HTTP 4xx/5xx (those are returned as statuses).","triggerScenarios":"Any gateway call when the in-sandbox gateway process is not listening on gateway_port: not started yet, crashed, still binding the port, or a port-race where another process grabbed the port. Connection refused/timeout inside the sandbox produces status=-1.","commonSituations":"Calling gateway APIs before the gateway finished startup; gateway crashed under load or OOM; gateway_port misconfigured; gateway container restarted while the client kept running.","solutions":["Check the 'error' field text — 'Connection refused' means nothing is listening on gateway_port in the sandbox","Probe `await gateway.health()` (it skips the diagnostic recursion) to confirm reachability","Wait/retry with backoff during gateway startup before making calls","Read gateway_log_path (the failure path auto-tails it at ERROR level) for the crash cause","Fix gateway_port if the gateway was configured to bind elsewhere"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"for _ in range(10):\n    if await gateway.health():\n        break\n    await asyncio.sleep(1)\nelse:\n    raise RuntimeError(\"gateway never became healthy\")","typeGuard":null,"tryCatchPattern":"for attempt in range(3):\n    try:\n        status, body = await gateway.exec_request(\"GET\", \"/mcps\", params={...})\n        break\n    except RuntimeError as e:\n        if \"gateway request failed\" not in str(e) or attempt == 2:\n            raise\n        await asyncio.sleep(2 ** attempt)","preventionTips":["Wait for health() before first use","Retry with backoff on startup port races","Monitor the gateway process; restart it on crash","Check gateway_log_path — the client auto-tails it on this failure"],"tags":["gateway","transport","connection-refused","sandbox"],"backgroundTag":"gateway-unreachable","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}