agentscope-ai/agentscope · critical · RuntimeError

Pod {self._pod_name!r} container is stuck: {msg}

Error message

Pod {self._pod_name!r} container is stuck: {msg}

What it means

Raised when the workspace Pod is Pending and a container's waiting reason matches a terminal set (e.g. CrashLoopBackOff, ImagePullBackOff, ErrImagePull, CreateContainerConfigError). Instead of waiting out the timeout, the library fails fast with the container's waiting message.

Source

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

            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"
                    ):
                        raise RuntimeError(
                            f"Pod {self._pod_name!r} is "
                            f"unschedulable: {cond.message}",
                        )

            await asyncio.sleep(delay)
            delay = min(delay * 1.5, 3.0)
        raise RuntimeError(
            f"Pod {self._pod_name!r} did not become Running "

View on GitHub (pinned to e90f1c7592)

Solutions

1. kubectl get pod <pod> -o jsonpath='{.status.containerStatuses[0].state.waiting}' to see reason/message
2. Fix the image reference or add imagePullSecrets to the workspace Pod spec
3. If CrashLoopBackOff, run the image locally or check container logs (kubectl logs --previous)
4. Supply any required env/ConfigMap/Secret the entrypoint expects

Example fix

# before
ws = K8sWorkspace(image="myrepo/agent-ws:lates")  # typo -> ImagePullBackOff -> 'is stuck'

# after
ws = K8sWorkspace(image="myrepo/agent-ws:latest", image_pull_secret="regcred")

null

null

try:
    await ws.start()
except RuntimeError as e:
    if "is stuck:" in str(e):
        reason = str(e).rsplit(":", 1)[-1].strip()
        # ImagePullBackOff / CrashLoopBackOff handling ...
        raise

When it happens

Trigger: Workspace image that cannot be pulled (bad tag, registry auth missing → ImagePullBackOff); container crashing on startup (CrashLoopBackOff from a failing entrypoint); missing ConfigMap/Secret referenced by the container (CreateContainerConfigError).

Common situations: Private registry without configured imagePullSecrets; typo'd image tag; entrypoint script referencing a missing env var; distroless image whose command fails immediately.

Related errors

• 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
• Pod {self._pod_name!r} entered {phase} state

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