GoogleContainerTools/skaffold · error

unable to load image %q into cluster: %w, %s

Error message

unable to load image %q into cluster: %w, %s

What it means

loadImages runs the kind/k3d load command (built by createCmd, e.g. `kind load docker-image`) for each artifact tag via util.RunCmdOut. This error is returned when that command exits non-zero, including the image tag, wrapped error, and the command's stdout output. It means the image could not be pushed into the cluster nodes.

Source

Thrown at pkg/skaffold/kubernetes/loader/load.go:160

		if knownImages == nil {
			var err error
			if knownImages, err = findKnownImages(ctx, i.cli); err != nil {
				return fmt.Errorf("unable to retrieve node's images: %w", err)
			}
		}
		normalizedImageRef, err := reference.ParseNormalizedNamed(artifact.Tag)
		if err != nil {
			return err
		}
		if stringslice.Contains(knownImages, normalizedImageRef.String()) {
			output.Green.Fprintln(out, "Found")
			continue
		}

		cmd := createCmd(artifact.Tag)
		if cmdOut, err := util.RunCmdOut(ctx, cmd); err != nil {
			output.Red.Fprintln(out, "Failed")
			return fmt.Errorf("unable to load image %q into cluster: %w, %s", artifact.Tag, err, cmdOut)
		}

		output.Green.Fprintln(out, "Loaded")
	}

	output.Default.Fprintln(out, "Images loaded in", timeutil.Humanize(time.Since(start)))
	return nil
}

func findKnownImages(ctx context.Context, cli *kubectl.CLI) ([]string, error) {
	nodeGetOut, err := cli.RunOut(ctx, "get", "nodes", `-ojsonpath={@.items[*].status.images[*].names[*]}`)
	if err != nil {
		return nil, fmt.Errorf("unable to inspect the nodes: %w", err)
	}

	knownImages := strings.Split(string(nodeGetOut), " ")
	return knownImages, nil
}

View on GitHub (pinned to a1189de023)

Solutions

1. Read the cmdOut in the error message — it contains the raw CLI failure
2. Confirm the image exists in the local daemon: `docker images <tag>`; rebuild with skaffold build if pruned
3. Run the load manually (e.g. `kind load docker-image <tag> --name <cluster>`) to isolate the issue
4. If using a non-Docker runtime, ensure the image is pushed/pulled via a registry instead of relying on load
5. Check node disk space (`kubectl get nodes`, describe nodes) if the CLI reports containerd write failures

Example fix

// before: image pruned before deploy
$ skaffold run  # -> unable to load image "img:tag" into cluster
// after: ensure build + load in one pipeline
$ skaffold dev  # builds then loads, or pre-load: kind load docker-image img:tag --name kind

// Ensure the image exists in the local daemon before load
if _, _, err := docker.ImageInspect(ctx, tag); err != nil {
    return fmt.Errorf("image %q not present locally, build first: %w", tag, err)
}

err := loader.LoadImages(ctx, out, artifacts)
for _, a := range artifacts {
    if err != nil && strings.Contains(err.Error(), fmt.Sprintf("unable to load image %q", a.Tag)) {
        log.Warnf("load failed for %s; falling back to registry push", a.Tag)
        if perr := pushToRegistry(ctx, a); perr == nil { continue }
    }
    return err
}

When it happens

Trigger: Skaffold deploying to kind/k3d where the load command for a specific artifact.Tag fails — image not present in the local Docker daemon, node name mismatch, or the CLI rejecting the tag (invalid reference).

Common situations: Built with podman/nerdctl while the load command assumes docker images; image was pruned between build and deploy; kind/k3d cluster recreated so node names changed; tag containing a registry hostname that the CLI mishandles; disk full on the node.

Related errors

• loading images into kind nodes: %w
• loading images into k3d nodes: %w
• unable to retrieve node's images: %w
• c.Message (pod status condition message)
• %q running container image %q errored during run with status

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