{"record":{"id":"ed11f4da0eea1c14","repo":"agentscope-ai/agentscope","slug":"gateway-port-must-be-none-or-an-integer-from-1-to","errorCode":null,"errorMessage":"gateway_port must be None or an integer from 1 to 65535.","messagePattern":"gateway_port must be None or an integer from 1 to 65535\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/workspace/_bubblewrap/_bubblewrap_workspace.py","lineNumber":181,"sourceCode":"        )\n        self._tmpdir: tempfile.TemporaryDirectory[str] | None = None\n        self._host_cache_dir = (\n            os.path.abspath(host_cache_dir) if host_cache_dir else \"\"\n        )\n        self._backend: BubblewrapBackend | None = None\n        self._gateway_process: asyncio.subprocess.Process | None = None\n\n    @staticmethod\n    def _validate_gateway_port(gateway_port: int | None) -> None:\n        \"\"\"Validate the configured TCP port before provisioning.\"\"\"\n        if gateway_port is None:\n            return\n        if (\n            isinstance(gateway_port, bool)\n            or not isinstance(gateway_port, int)\n            or not 1 <= gateway_port <= 65535\n        ):\n            raise ValueError(\n                \"gateway_port must be None or an integer from 1 to 65535.\",\n            )\n\n    @property\n    def is_persistent(self) -> bool:\n        \"\"\"Whether the workspace files survive ``close``.\"\"\"\n        return self._host_workdir_input is not None\n\n    async def _provision_backend(self) -> None:\n        \"\"\"Validate Bubblewrap availability and bind the backend.\"\"\"\n        if not sys.platform.startswith(\"linux\"):\n            raise RuntimeError(\"BubblewrapWorkspace requires Linux.\")\n        if shutil.which(\"bwrap\") is None:\n            raise RuntimeError(\"BubblewrapWorkspace requires 'bwrap' on PATH.\")\n        await self._probe_bubblewrap()\n        if self._host_workdir_input is None:\n            self._owned_workdir = tempfile.TemporaryDirectory()\n            self.host_workdir = self._owned_workdir.name","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/workspace/_bubblewrap/_bubblewrap_workspace.py#L163-L199","documentation":"_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.","triggerScenarios":"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.","commonSituations":"Ports parsed from environment/config as strings; derived port arithmetic producing out-of-range values; passing a boolean flag by mistake.","solutions":["Coerce to int and range-check before constructing: p = int(p) if p not in (None,'') else None","Pick a valid port (e.g. 127.0.0.1 ephemeral range like 20000-60000)","Ensure config schema types the field as integer|null, never string or bool"],"exampleFix":"# before\nws = BubblewrapWorkspace(gateway_port=os.environ.get('GW_PORT'))  # '9000' str\n# after\nport = os.environ.get('GW_PORT')\nws = BubblewrapWorkspace(gateway_port=int(port) if port else None)","handlingStrategy":"type-guard","validationCode":"port = int(raw) if raw not in (None, '',) else None\nassert port is None or (isinstance(port, int) and not isinstance(port, bool) and 1 <= port <= 65535)","typeGuard":"def is_valid_gateway_port(p) -> bool:\n    return p is None or (isinstance(p, int) and not isinstance(p, bool) and 1 <= p <= 65535)","tryCatchPattern":"null","preventionTips":["Parse env/config ports to int explicitly","Never allow bools through config typing"],"tags":["bubblewrap","port","validation","config"],"backgroundTag":"port-out-of-range","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}