kubernetes/kops · error

error pulling docker image with '%s': %v: %s

Error message

error pulling docker image with '%s': %v: %s

What it means

The pull_image task builds a docker pull command, executes it with exec.Command, and if the command exits non-zero wraps the combined stderr/stdout into this error. It means docker itself reported a failure pulling the container image (not a kOps-level validation failure).

Source

Thrown at upup/pkg/fi/nodeup/nodetasks/pull_image.go:67

}

func (t *PullImageTask) GetName() *string {
	if t.Name == "" {
		return nil
	}
	return &t.Name
}

func (e *PullImageTask) Run(c *fi.NodeupContext) error {
	// Pull the container image
	args := []string{"ctr", "--namespace", "k8s.io", "images", "pull", e.Name}
	human := strings.Join(args, " ")

	klog.Infof("running command %s", human)
	cmd := exec.Command(args[0], args[1:]...)
	output, err := cmd.CombinedOutput()
	if err != nil {
		return fmt.Errorf("error pulling docker image with '%s': %v: %s", human, err, string(output))
	}

	return nil
}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Inspect the combined output in the error for the docker-level cause (e.g. 'manifest unknown', 'unauthorized', 'Cannot connect to the daemon').
2. Verify the image reference (registry/repo:tag) exists and the node can reach the registry.
3. Configure registry credentials (docker login / credHelpers in /root/.docker/config.json) for private registries.
4. Ensure the docker daemon is running: systemctl status docker.

Example fix

// before
dockerPull: registry.example.com/private/app:v1
// after: ensure auth then correct tag
dockerPull: registry.example.com/private/app:v1.2.3  # tag exists, creds configured

if err := exec.Command("docker", "manifest", "inspect", imageRef).Run(); err != nil {
    return fmt.Errorf("image %s not resolvable before pull", imageRef)
}

if err != nil {
    if strings.Contains(string(output), "toomanyrequests") || strings.Contains(string(output), "connection refused") {
        // retry with backoff; otherwise fail fast
    }
}

When it happens

Trigger: `docker pull <image>` fails: image not found in the registry, registry auth required, no network/DNS to the registry, or the docker daemon is down.

Common situations: Typo'd or deleted image tag in a hook/manifest; private registry (ECR/GCR) without credentials on the node; rate limiting from Docker Hub; EKS/K8s nodes without registry pull secrets.

Related errors

• fetching %q: %v
• failed to copy index: %v
• failed to copy image: %v
• building nodeConfig for instanceGroup: %w
• marshalling nodeupConfig: %w

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/0d89383192a1cd47. Report an issue: GitHub.