GoogleContainerTools/skaffold · error

pulling init container image

Error message

pulling init container image

What it means

When debug init containers are generated, Skaffold pulls each support image (e.g. a debugger helper image) into the local Docker daemon via client.Pull before creating the container. A pull failure (registry unreachable, image not found, auth missing) is wrapped with this message.

Source

Thrown at pkg/skaffold/deploy/docker/deploy.go:262

		provide necessary debugging files into the application container. These files are
		shared via a volume created by the init container. We only need to create each init container
		once, so we track the mounts on the DebugManager. These mounts are then added to the container
		configuration before creating the container in the daemon.

		NOTE: All tracked mounts (and created init containers) are assumed to be in the same Docker daemon,
		configured implicitly on the system. The tracking on the DebugManager will need to be updated to account
		for the active daemon if this is ever extended to support multiple active Docker daemons.
	*/
	for _, c := range initContainers {
		labels := d.labeller.DebugLabels()

		if d.debugger.HasMount(c.Image) {
			// skip duplication of init containers
			continue
		}
		// pull the debug support image into the local daemon
		if err := d.client.Pull(ctx, out, c.Image, v1.Platform{}); err != nil {
			return nil, errors.Wrap(err, "pulling init container image")
		}

		// create the volume used by the init container
		v, err := d.client.VolumeCreate(ctx, client.VolumeCreateOptions{
			Labels: labels,
		})
		if err != nil {
			return nil, err
		}

		m := d.createMount(v, labels)

		// create the init container
		c.Labels = labels
		_, _, id, err := d.client.Run(ctx, out, dockerutil.ContainerCreateOpts{
			ContainerConfig: c,
			Mounts:          []mount.Mount{m},
		})

View on GitHub (pinned to a1189de023)

Solutions

1. Pull the failing image manually to reproduce: `docker pull <init-container-image>`
2. Run `docker login` against the registry hosting the debug support image
3. Check network/proxy connectivity to the registry (VPN, corporate proxy env vars)
4. Pin a published support image version / upgrade or downgrade Skaffold so the referenced tag exists
5. Retry after transient registry failures (e.g. Docker Hub toomanyrequests)

Example fix

// before
$ skaffold debug
error: pulling init container image: ... unauthorized: authentication required
// after
$ docker login registry.example.com
$ skaffold debug  # proceeds

img := "<init-container-image>"
if out, err := exec.Command("docker", "pull", img).CombinedOutput(); err != nil {
  return fmt.Errorf("support image %s not pullable: %v: %s", img, err, out)
}

null

err := deploy(ctx)
for i := 0; i < 3 && err != nil && strings.Contains(err.Error(), "pulling init container image"); i++ {
  time.Sleep(2*time.Second << i)
  err = deploy(ctx)
}

When it happens

Trigger: setupDebugging iterates the init containers from TransformImage; for any image where d.debugger.HasMount(c.Image) is false it calls d.client.Pull(ctx, out, c.Image, v1.Platform{}), which errors — network outage, unknown tag, or unauthenticated private registry.

Common situations: Corporate network/proxy blocking the registry hosting debug support images; support image tag no longer published (Skaffold upgrade mismatch); private registry requiring `docker login`; rate limiting from Docker Hub.

Related errors

• STATUSCHECK_IMAGE_PULL_ERR
• getting auth config: %w
• getting auth config for %q: %w
• %s %q: %w
• pulling image from repository: %w

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/bb4e0242759c7373. Report an issue: GitHub.