{"record":{"id":"fcd49f2803f1f194","repo":"agentscope-ai/agentscope","slug":"failed-to-start-container-self-container-name-r","errorCode":null,"errorMessage":"Failed to start container {self._container_name!r}: {stderr.decode(errors='replace')}","messagePattern":"Failed to start container (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/agentscope/workspace/_applecontainer/_applecontainer_workspace.py","lineNumber":437,"sourceCode":"                    self._container_name,\n                )\n                return\n\n        # Start the container.\n        logger.info(\n            \"AppleContainerWorkspace: starting container %r ...\",\n            self._container_name,\n        )\n        process = await asyncio.create_subprocess_exec(\n            \"container\",\n            \"start\",\n            self._container_name,\n            stdout=asyncio.subprocess.PIPE,\n            stderr=asyncio.subprocess.PIPE,\n        )\n        _, stderr = await process.communicate()\n        if process.returncode != 0:\n            raise RuntimeError(\n                f\"Failed to start container {self._container_name!r}: \"\n                f\"{stderr.decode(errors='replace')}\",\n            )\n\n    async def _create_and_start_container(self) -> None:\n        \"\"\"Create and start the container via ``container run -d``.\n\n        The container runs ``sleep infinity`` to stay alive while the\n        gateway is managed independently.\n        \"\"\"\n        run_cmd: list[str] = [\n            \"container\",\n            \"run\",\n            \"-d\",\n            \"--name\",\n            self._container_name,\n            \"--cpus\",\n            str(self.cpus),","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/workspace/_applecontainer/_applecontainer_workspace.py#L419-L455","documentation":"Raised when `container start` (Apple Containers CLI) returns a non-zero exit code while _start_container_if_stopped attempts to restart a stopped container. The message embeds the container name and the decoded stderr from the CLI subprocess. It indicates the container exists but the runtime refused to start it.","triggerScenarios":"Calling workspace APIs that trigger _provision_backend (initialization/reattach) when the named AppleContainer is in a stopped state and the `container start` subprocess fails (e.g. container runtime not running, invalid image state, port conflicts, corrupted container).","commonSituations":"Apple Container framework daemon not running on macOS, container left in a broken state after a host reboot or OOM kill, name collision with a half-created container, macOS/version mismatch of the container CLI.","solutions":["Inspect the embedded stderr — it is the direct output of `container start <name>`","Verify the container exists and inspect its state: `container list --all` and `container inspect <name>`","Try starting it manually to reproduce: `container start <name>`","Delete and reprovision the broken container if state is unrecoverable (remove the stale container and re-initialize the workspace)","Ensure the Apple Containers runtime/daemon and macOS version are supported"],"exampleFix":"# before: stale/broken container blocks provisioning\n# container inspect my-sand shows status=stopped, start fails\nclass MyWS(AppleContainerWorkspace):\n    async def _start_container_if_stopped(self):\n        try:\n            await super()._start_container_if_stopped()\n        except RuntimeError as e:\n            # fall back to recreating the container from scratch\n            await self._delete_container()\n            await self._create_and_start_container()","handlingStrategy":"fallback","validationCode":"# before provisioning, check container state via the CLI\nimport asyncio\nasync def container_exists(name: str) -> bool:\n    p = await asyncio.create_subprocess_exec(\n        'container', 'inspect', name,\n        stdout=asyncio.subprocess.DEVNULL, stderr=asyncio.subprocess.DEVNULL)\n    return await p.wait() == 0","typeGuard":null,"tryCatchPattern":"try:\n    await ws.initialize()  # or async with ws\nexcept RuntimeError as e:\n    if 'Failed to start container' in str(e):\n        # recreate container or surface actionable error\n        ...\n    raise","preventionTips":["Keep the Apple Containers runtime/daemon running before initializing workspaces","Add health checks that recreate unrecoverable containers","Clean up containers on shutdown to avoid stale states"],"tags":["applecontainer","macos","container-start","subprocess","runtime"],"backgroundTag":"container-start-failed","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}