agentscope-ai/agentscope · critical · RuntimeError

Pod {self._pod_name!r} entered {phase} state

Error message

Pod {self._pod_name!r} entered {phase} state

What it means

Raised while waiting for the workspace Pod to become Running: the Pod's phase transitioned to Failed or Unknown, meaning the container crashed or the kubelet lost track of it. The library surfaces this instead of waiting until the timeout so the failure reason can be inspected quickly.

Source

Thrown at src/agentscope/workspace/_k8s/_k8s_workspace.py:533

                "CrashLoopBackOff",
            },
        )
        _UNSCHEDULABLE_TYPES = frozenset(
            {"PodScheduled"},
        )

        deadline = asyncio.get_event_loop().time() + timeout
        delay = 0.5
        while asyncio.get_event_loop().time() < deadline:
            pod = await self._v1.read_namespaced_pod(
                self._pod_name,
                self._namespace,
            )
            phase = pod.status.phase if pod.status else None
            if phase == "Running":
                return
            if phase in ("Failed", "Unknown"):
                raise RuntimeError(
                    f"Pod {self._pod_name!r} entered {phase} state",
                )

            if phase == "Pending" and pod.status:
                for cs in pod.status.container_statuses or []:
                    if cs.state and cs.state.waiting:
                        reason = cs.state.waiting.reason or ""
                        if reason in _TERMINAL_WAITING_REASONS:
                            msg = cs.state.waiting.message or reason
                            raise RuntimeError(
                                f"Pod {self._pod_name!r} container "
                                f"is stuck: {msg}",
                            )
                for cond in pod.status.conditions or []:
                    if (
                        cond.type in _UNSCHEDULABLE_TYPES
                        and cond.status == "False"
                        and cond.reason == "Unschedulable"

View on GitHub (pinned to e90f1c7592)

Solutions

1. kubectl describe pod <pod> and read the container statuses / events for the real cause
2. If OOMKilled, raise the Pod's memory limits in the workspace Pod spec
3. Verify the image reference and imagePullSecrets are correct and reachable
4. If phase Unknown, check node health (kubectl get nodes) and reschedule

Example fix

# before
backend = await ws._provision_backend()  # RuntimeError: Pod entered Failed state

# after
# inspect first: kubectl describe pod <pod-name>; fix limits/image, then
ws = K8sWorkspace(..., resources={"memory": "1Gi"})
backend = await ws._provision_backend()

null

null

try:
    await ws.start()
except RuntimeError as e:
    if "entered" in str(e) and "state" in str(e):
        # run kubectl describe pod; classify OOM vs crash
        raise

When it happens

Trigger: Workspace Pod container exiting immediately (bad image entrypoint, OOMKilled surfaced as Failed); node loss making the phase Unknown; image pull backoff escalating to failure on some cluster configurations.

Common situations: Wrong or missing image tag/ImagePullSecret; entrypoint error in a custom workspace image; memory limits too low causing repeated OOM kills; node notReady events.

Related errors

• Failed to pull image {self.base_image!r}: {stderr.decode(err
• not found in Pod: {path}
• not found in Pod: {path} (tar stderr: {stderr_text})
• write to {path!r} failed: {command[0]} exited {exit_code}: {
• PVC {pvc_name!r} did not finish deleting within {timeout}s

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