FoundationAgents/OpenManus · critical · RuntimeError

Failed to ensure Docker image: {config.image}

Error message

Failed to ensure Docker image: {config.image}

What it means

Raised by SandboxManager.create_sandbox (app/sandbox/core/manager.py:139) when self.ensure_image(config.image) returns False, meaning the manager could not confirm the image exists locally or pull/build it. Nothing container-related has started yet — the failure is purely image availability: bad tag, registry unreachable, missing registry credentials, or a Docker daemon problem.

Source

Thrown at app/sandbox/core/manager.py:139

        Args:
            config: Sandbox configuration.
            volume_bindings: Volume mapping configuration.

        Returns:
            str: Sandbox ID.

        Raises:
            RuntimeError: If max sandbox count reached or creation fails.
        """
        async with self._global_lock:
            if len(self._sandboxes) >= self.max_sandboxes:
                raise RuntimeError(
                    f"Maximum number of sandboxes ({self.max_sandboxes}) reached"
                )

            config = config or SandboxSettings()
            if not await self.ensure_image(config.image):
                raise RuntimeError(f"Failed to ensure Docker image: {config.image}")

            sandbox_id = str(uuid.uuid4())
            try:
                sandbox = DockerSandbox(config, volume_bindings)
                await sandbox.create()

                self._sandboxes[sandbox_id] = sandbox
                self._last_used[sandbox_id] = asyncio.get_event_loop().time()
                self._locks[sandbox_id] = asyncio.Lock()

                logger.info(f"Created sandbox {sandbox_id}")
                return sandbox_id

            except Exception as e:
                logger.error(f"Failed to create sandbox: {e}")
                if sandbox_id in self._sandboxes:
                    await self.delete_sandbox(sandbox_id)
                raise RuntimeError(f"Failed to create sandbox: {e}")

View on GitHub (pinned to 52a13f2a57)

Solutions

  1. Run `docker pull <config.image>` manually on the host to see the real underlying error.
  2. Verify the image tag spelling and registry prefix (e.g. docker.io/library/python:3.11-slim).
  3. Pre-build/pre-pull the image on the host so ensure_image finds it in the local cache.
  4. Check the Docker daemon is running and the user has permission on /var/run/docker.sock; configure registry credentials for private images.
Defensive patterns

Strategy: try-catch

Validate before calling

import docker
client = docker.from_env()
try:
    client.images.get(config.image)
except docker.errors.ImageNotFound:
    client.images.pull(config.image)  # fail here with the real registry error

Try / catch

try:
    sid = await manager.create_sandbox(config)
except RuntimeError as e:
    if "Failed to ensure Docker image" in str(e):
        log.error("image %s unavailable — check registry/daemon", config.image); raise

Prevention

When it happens

Trigger: config.image names a tag that does not exist in the local cache or the registry (typo, missing prefix like 'library/'); Docker daemon is stopped or unreachable; private registry requires auth that is not configured; rate-limited pulls from Docker Hub.

Common situations: Air-gapped or proxied environments where docker pull fails; CI runners with a cold cache and Hub rate limits; a custom image that was renamed but SandboxSettings defaults were not updated; rootless Docker socket permission issues.

Related errors

AI-assisted analysis of FoundationAgents/OpenManus@52a13f2a57 (2026-08-15). Data as JSON: /api/errors/cbf9847fd12ccffc. Report an issue: GitHub.