Image Pull Failed

Symptom

A session.create or image.pull job fails:


ERROR  image_pull_failed image=ghcr.io/curate-me-ai/openclaw-base:vYYYY.M.D
       attempts=3 last_error="manifest unknown" | "no space left on device" |
       "denied: requested access to the resource is denied" | "timeout"

The dashboard shows the launch as failed with the same image_pull_failed reason on the machine card.

Likely causes

Error suffix	Cause	Fix
`manifest unknown`	The exact tag was retracted or never published	Use a current tag (see Image Registry).
`denied: requested access...`	The image lives in a private repo your host can’t auth to	Add registry credentials — see Private registry auth.
`no space left on device`	Host disk is full	Prune unused images / volumes.
`dial tcp ... timeout`	Egress to `ghcr.io` (or the configured mirror) is blocked	Open firewall — see Egress requirements.
`unexpected EOF`	Flaky connection mid-pull	Retry. ImageManager already retries 3x; if it still fails the network path is too lossy for large images.

Fix

Image registry

The default image registry for cm-runner is ghcr.io/curate-me-ai/. The legacy localhost:5000/curate-me/ and the deleted services/runner-agent/ source tree are no longer used.

Current production tags follow the OpenClaw release cadence — list them via the dashboard’s Templates → Verify Image action, or directly from GHCR:


crane ls ghcr.io/curate-me-ai/openclaw-base | tail -10

Private registry auth

If your org uses a private mirror or custom-built images, give the agent’s host a docker login:


echo "$REGISTRY_TOKEN" | docker login ghcr.io -u USERNAME --password-stdin

The agent runs Docker calls as the host’s daemon, so it inherits the host’s ~/.docker/config.json credentials. Restart the agent container after logging in so the next docker pull picks up the credential helper:


docker restart cm-runner

Egress requirements

The agent’s host must reach:

ghcr.io (443) — image registry
api.curate-me.ai (443) — control plane
Any LLM provider you use (e.g. api.anthropic.com, api.openai.com) — for in-runner LLM calls, proxied through the gateway

If your network restricts egress, allowlist these hosts.

Disk space


docker system df

Free space by pruning images you no longer need:


docker image prune -a --filter "until=168h"   # remove images unused for 7 days
docker volume prune                            # remove dangling volumes

Runner images cache 1–4 GB each. For an agent that runs 5 different templates, budget at least 20 GB of free disk. See Connect Your Machine for the recommended VM sizing.

Pre-pull to avoid first-launch failures

Once you know which templates a machine will run, opt the machine into pre-pulling so failures show up at policy-set time, not at the customer’s first session launch. The dashboard’s machine card has a Pre-pull images action; the API equivalent is:


curl -X POST \
  -H "X-CM-API-Key: cm_sk_your_key_here" \
  -H "Content-Type: application/json" \
  https://api.curate-me.ai/gateway/admin/runners/byovm/agents/$AGENT_ID/pre-pull \
  -d '{"image_ref": "ghcr.io/curate-me-ai/openclaw-base:latest"}'

The agent reports the pull result on its next heartbeat.

Where to find logs


docker logs cm-runner --tail 200 | grep -E "image.pull|pull_failed|pulling"

Server-side: byovm_job_failed in gateway logs with job_type=image.pull.

OpenClaw Boot Failed — what happens next once the image pulls but the container won’t start
Runner Startup SLO