GoogleContainerTools/skaffold · error

loading images into k3d nodes: %w

Error message

loading images into k3d nodes: %w

What it means

LoadImages detects a k3d cluster from the kubeContext and delegates image loading to the k3d CLI via loadImagesInK3dNodes. This error wraps any failure from that path — the k3d CLI missing, cluster not found, or the k3d image import command failing. k3d, like kind, requires images to be explicitly imported into node containerd/docker.

Source

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

	}

	artifacts := imagesToLoad(localImages, deployerImages, images)

	if config.IsKindCluster(i.kubeContext) {
		kindCluster := config.KindClusterName(currentContext.Cluster)

		// With `kind`, docker images have to be loaded with the `kind` CLI.
		if err := i.loadImagesInKindNodes(ctx, out, kindCluster, artifacts); err != nil {
			return fmt.Errorf("loading images into kind nodes: %w", err)
		}
	}

	if config.IsK3dCluster(i.kubeContext) {
		k3dCluster := config.K3dClusterName(currentContext.Cluster)

		// With `k3d`, docker images have to be loaded with the `k3d` CLI.
		if err := i.loadImagesInK3dNodes(ctx, out, k3dCluster, artifacts); err != nil {
			return fmt.Errorf("loading images into k3d nodes: %w", err)
		}
	}

	return nil
}

// loadImagesInKindNodes loads artifact images into every node of a kind cluster.
func (i *ImageLoader) loadImagesInKindNodes(ctx context.Context, out io.Writer, kindCluster string, artifacts []graph.Artifact) error {
	output.Default.Fprintln(out, "Loading images into kind cluster nodes...")
	return i.loadImages(ctx, out, artifacts, func(tag string) *exec.Cmd {
		return exec.CommandContext(ctx, "kind", "load", "docker-image", "--name", kindCluster, tag)
	})
}

// loadImagesInK3dNodes loads artifact images into every node of a k3s cluster.
func (i *ImageLoader) loadImagesInK3dNodes(ctx context.Context, out io.Writer, k3dCluster string, artifacts []graph.Artifact) error {
	output.Default.Fprintln(out, "Loading images into k3d cluster nodes...")
	return i.loadImages(ctx, out, artifacts, func(tag string) *exec.Cmd {

View on GitHub (pinned to a1189de023)

Solutions

1. Install/verify the k3d CLI (`k3d version`) and ensure it is on PATH
2. List clusters (`k3d cluster list`) and confirm the cluster named by the current context exists and is running
3. Verify Docker is running and the image tag exists locally (`docker images <tag>`)
4. Run `k3d image import <tag> -c <cluster>` manually to see the underlying error
5. Fix the kubeconfig so the context/cluster naming matches the k3d cluster name

Example fix

// before: stale k3d context
current-context: k3d-old-cluster
// after: use the live k3d cluster
kubectl config use-context k3d-mycluster
# or recreate it: k3d cluster create mycluster

// Before running skaffold against k3d
if _, err := exec.LookPath("k3d"); err != nil {
    return fmt.Errorf("k3d CLI not found on PATH: %w", err)
}
out, _ := exec.Command("k3d", "cluster", "list").Output()
if !strings.Contains(string(out), clusterName) {
    return fmt.Errorf("k3d cluster %q not found", clusterName)
}

err := loader.LoadImages(ctx, out, artifacts)
if err != nil {
    if strings.Contains(err.Error(), "loading images into k3d nodes") {
        log.Warnf("k3d import failed: %v", err)
        return pushToRegistry(ctx, artifacts) // fallback
    }
    return err
}

When it happens

Trigger: Running skaffold dev/run/deploy/verify with a kubeContext detected as k3d (config.IsK3dCluster), and loadImagesInK3dNodes fails: k3d binary absent, K3dClusterName resolves to a non-existent cluster, or `k3d image import` exits non-zero.

Common situations: k3d CLI not installed or an old version with different CLI flags; the k3d cluster was deleted but the kubeconfig context remains; Docker daemon down so the built image isn't available for import; cluster name mismatch because the context was renamed.

Related errors

• loading images into kind nodes: %w
• unable to load image %q into cluster: %w, %s
• kubectl delete: %w
• unable to retrieve node's images: %w
• %s is not a valid Kubernetes manifest

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