agentscope-ai/agentscope · critical · RuntimeError

gateway request failed: {env.get('error', 'unknown error')}

Error message

gateway request failed: {env.get('error', 'unknown error')}

What it means

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).

Source

Thrown at src/agentscope/workspace/_gateway_client.py:685

                        pass

            if result.exit_code != 0:
                raise RuntimeError(
                    f"gateway shim exited with {result.exit_code}: "
                    f"{result.stderr.decode(errors='replace')[:500]}",
                )

            try:
                env = json.loads(result.stdout)
            except Exception as e:
                raise RuntimeError(
                    "gateway shim produced non-JSON stdout: "
                    f"{result.stdout[:200]!r}",
                ) from e

            status = int(env["status"])
            if status == -1:
                raise RuntimeError(
                    "gateway request failed: "
                    f"{env.get('error', 'unknown error')}",
                )

            if "body_file" in env:
                spilled = env["body_file"]
                body_bytes = await self.backend.read_file(spilled)
                try:
                    await self.backend.delete_path(spilled)
                except Exception:
                    pass
            else:
                body_bytes = base64.b64decode(env.get("body", ""))

            return status, body_bytes
        except Exception as exc:
            # ``/health`` never triggers diagnosis — otherwise a dead
            # gateway would recursively probe itself.

View on GitHub (pinned to e90f1c7592)

Solutions

1. Check the 'error' field text — 'Connection refused' means nothing is listening on gateway_port in the sandbox
2. Probe `await gateway.health()` (it skips the diagnostic recursion) to confirm reachability
3. Wait/retry with backoff during gateway startup before making calls
4. Read gateway_log_path (the failure path auto-tails it at ERROR level) for the crash cause
5. Fix gateway_port if the gateway was configured to bind elsewhere

for _ in range(10):
    if await gateway.health():
        break
    await asyncio.sleep(1)
else:
    raise RuntimeError("gateway never became healthy")

for attempt in range(3):
    try:
        status, body = await gateway.exec_request("GET", "/mcps", params={...})
        break
    except RuntimeError as e:
        if "gateway request failed" not in str(e) or attempt == 2:
            raise
        await asyncio.sleep(2 ** attempt)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• gateway shim exited with {result.exit_code}: {result.stderr.
• gateway shim produced non-JSON stdout: {result.stdout[:200]!
• {left_name} must not overlap {right_name}.
• not found in Bubblewrap sandbox: {path}
• Bubblewrap read_file failed (exit {result.exit_code}): {resu

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/fb1bde8d3b48dccd. Report an issue: GitHub.