ContextQMD
Back to Mcpproxy Go

MCPX_DOCKER_IMAGE_PULL_FAILED

docs/errors/MCPX_DOCKER_IMAGE_PULL_FAILED.md

0.38.11.5 KB
Original Source

MCPX_DOCKER_IMAGE_PULL_FAILED

Severity: error Domain: Docker

What happened

Before starting an isolated upstream, mcpproxy needs the runtime image (e.g. python:3.12-slim for uvx, node:20-alpine for npx). Pulling failed.

Common causes

  • No internet connectivity at the moment.
  • Registry rate-limit (Docker Hub anonymous limit is 100 pulls / 6h per IP).
  • The image name in isolation.image is wrong.
  • A corporate registry mirror is required and isn't configured.
  • Disk full — pull aborted mid-stream.

How to fix

Pull manually to see the underlying error

bash
docker pull <image>

Docker's own error is more specific than the wrapped one mcpproxy surfaces.

Authenticate against Docker Hub

If you're hitting rate-limits:

bash
docker login

A free Docker Hub account doubles the limit and gives you predictable resets.

Configure a registry mirror

Many corporate networks require a private mirror. Configure it once in ~/.docker/daemon.json (or per-platform equivalent):

json
{ "registry-mirrors": ["https://registry.example.com"] }

Restart Docker after editing.

Free up disk

bash
docker system df          # see what's using space
docker system prune -a    # nuke unused images/containers (destructive — review first)