agentscope-ai/agentscope · critical · RuntimeError

gateway shim exited with {result.exit_code}: {result.stderr.

Error message

gateway shim exited with {result.exit_code}: {result.stderr.decode(errors='replace')[:500]}

What it means

Raised by GatewayClient.exec_request() when the `python3 -c SHIM_SCRIPT ...` process executed inside the sandbox exits non-zero. The shim is the tiny Python HTTP relay that runs in the sandbox and talks to 127.0.0.1:gateway_port; its stderr (first 500 chars) is included. This means the relay itself crashed before/while making the request — not that the gateway returned an error status.

Source

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

                        SHIM_SCRIPT,
                        method,
                        f"http://127.0.0.1:{self.gateway_port}{path}",
                        body_file,
                        str(self.inline_limit),
                        self.tmp_dir,
                        (self.auth_token or "") if include_auth else "",
                    ],
                    timeout=self.timeout,
                )
            finally:
                if wrote_body_file is not None:
                    try:
                        await self.backend.delete_path(wrote_body_file)
                    except Exception:
                        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')}",
                )

View on GitHub (pinned to e90f1c7592)

Solutions

Check the embedded stderr text — it names the actual Python traceback reason
Verify `python3` exists inside the sandbox: `await backend.exec_shell(["python3", "--version"])`
Increase GatewayClient timeout if stderr says 'timed out'
Reduce payload size or raise inline_limit if the failure correlates with large bodies
Match sandbox image to a known-good version that ships python3

Defensive patterns

Strategy: fallback

Validate before calling

res = await backend.exec_shell(["python3", "-c", "print('ok')"])
if not res.ok():
    raise RuntimeError(f"sandbox lacks python3: {res.stderr[:200]!r}")

Try / catch

try:
    status, body = await gateway.exec_request(...)
except RuntimeError as e:
    if "gateway shim exited" in str(e):
        # shim-level crash: surface stderr, degrade gracefully
        return None
    raise

Prevention

Verify python3 exists in the sandbox image before creating GatewayClient
Pin a sandbox image known to include python3
Set an adequate timeout for slow sandboxes
Cap payload sizes to avoid shim OOM

When it happens

Trigger: Any gateway call (connect/close/list tools/health/list_mcps/tool invocation) when the sandbox lacks python3, the shim script hits an unhandled exception (bad URL encoding, missing module), exec times out (exit code reflects timeout, stderr 'timed out'), or the sandbox killed the process (OOM).

Common situations: Minimal container images without python3; sandbox image updated and python3 removed/moved; oversized or malformed body causing shim exception; exec timeout too small on slow sandboxes; OOM-killed shim on very large tool payloads.

Related errors

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