agentscope-ai/agentscope · error · ValueError

gateway_port must be None or an integer from 1 to 65535.

Error message

gateway_port must be None or an integer from 1 to 65535.

What it means

_validate_gateway_port accepts only None or an int in 1..65535. bools are explicitly rejected (isinstance(True, int) is True in Python), as are out-of-range values and non-int types like strings.

Source

Thrown at src/agentscope/workspace/_bubblewrap/_bubblewrap_workspace.py:181

        )
        self._tmpdir: tempfile.TemporaryDirectory[str] | None = None
        self._host_cache_dir = (
            os.path.abspath(host_cache_dir) if host_cache_dir else ""
        )
        self._backend: BubblewrapBackend | None = None
        self._gateway_process: asyncio.subprocess.Process | None = None

    @staticmethod
    def _validate_gateway_port(gateway_port: int | None) -> None:
        """Validate the configured TCP port before provisioning."""
        if gateway_port is None:
            return
        if (
            isinstance(gateway_port, bool)
            or not isinstance(gateway_port, int)
            or not 1 <= gateway_port <= 65535
        ):
            raise ValueError(
                "gateway_port must be None or an integer from 1 to 65535.",
            )

    @property
    def is_persistent(self) -> bool:
        """Whether the workspace files survive ``close``."""
        return self._host_workdir_input is not None

    async def _provision_backend(self) -> None:
        """Validate Bubblewrap availability and bind the backend."""
        if not sys.platform.startswith("linux"):
            raise RuntimeError("BubblewrapWorkspace requires Linux.")
        if shutil.which("bwrap") is None:
            raise RuntimeError("BubblewrapWorkspace requires 'bwrap' on PATH.")
        await self._probe_bubblewrap()
        if self._host_workdir_input is None:
            self._owned_workdir = tempfile.TemporaryDirectory()
            self.host_workdir = self._owned_workdir.name

View on GitHub (pinned to e90f1c7592)

Solutions

1. Coerce to int and range-check before constructing: p = int(p) if p not in (None,'') else None
2. Pick a valid port (e.g. 127.0.0.1 ephemeral range like 20000-60000)
3. Ensure config schema types the field as integer|null, never string or bool

Example fix

# before
ws = BubblewrapWorkspace(gateway_port=os.environ.get('GW_PORT'))  # '9000' str
# after
port = os.environ.get('GW_PORT')
ws = BubblewrapWorkspace(gateway_port=int(port) if port else None)

port = int(raw) if raw not in (None, '',) else None
assert port is None or (isinstance(port, int) and not isinstance(port, bool) and 1 <= port <= 65535)

def is_valid_gateway_port(p) -> bool:
    return p is None or (isinstance(p, int) and not isinstance(p, bool) and 1 <= p <= 65535)

null

When it happens

Trigger: gateway_port=0, 65536, -1, '8080', or True/False. Note a port of 0 (OS auto-assign) is not allowed because the port must be known in advance for cross-execution reachability.

Common situations: Ports parsed from environment/config as strings; derived port arithmetic producing out-of-range values; passing a boolean flag by mistake.

Related errors

• host_workdir must not be empty.
• host_cache_dir must not be empty.
• The injection template must contain the '{runtime_state}' pl
• MCP {card.name!r} produced an invalid client: {e}
• DimensionPolicy: kind=ANY requires dimension=None, got dimen

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