kubernetes/kops · error

error remapping images: %v

Error message

error remapping images: %v

What it means

AssetBuilder.RemapManifest wraps any error returned while remapping the container images of objects parsed from a manifest YAML. The underlying failure came from one of the objects' RemapImages callbacks (a.RemapImage), typically a failure to compute or resolve a remapped image URL/hash. The %v is the root cause, so the real fix depends on the wrapped error text.

Source

Thrown at pkg/assets/builder.go:250

		return snapshot[i].Path < snapshot[j].Path
	})

	return snapshot
}

// RemapManifest transforms a kubernetes manifest.
// Whenever we are building a Task that includes a manifest, we should pass it through RemapManifest first.
// This will:
// * rewrite the images if they are being redirected to a mirror, and ensure the image is uploaded
func (a *AssetBuilder) RemapManifest(data []byte) ([]byte, error) {
	objects, err := kubemanifest.LoadObjectsFrom(data)
	if err != nil {
		return nil, err
	}

	for _, object := range objects {
		if err := object.RemapImages(a.RemapImage); err != nil {
			return nil, fmt.Errorf("error remapping images: %v", err)
		}
	}

	return objects.ToYAML()
}

// RemapImage normalizes a containers location if a user sets the AssetsLocation ContainerRegistry location.
func (a *AssetBuilder) RemapImage(image string) string {
	asset := &ImageAsset{
		DownloadLocation:  image,
		CanonicalLocation: image,
	}

	if strings.HasPrefix(image, "registry.k8s.io/kops/dns-controller:") {
		// To use user-defined DNS Controller:
		// 1. DOCKER_REGISTRY=[your docker hub repo] make dns-controller-push
		// 2. export DNSCONTROLLER_IMAGE=[your docker hub repo]
		// 3. make kops and create/apply cluster

View on GitHub (pinned to 4c8573c808)

Solutions

1. Read the wrapped %v cause and fix the underlying image (bad reference, missing hash, unreachable registry).
2. If using a file/oci assets mirror, run 'kops get assets --copy' to stage all images, then retry.
3. Verify AssetsLocation/registry settings on the AssetBuilder match the staged mirror.
4. Test the manifest standalone with TestRemapEmptySection-style parsing to find the offending object/image.

Example fix

// before
assetBuilder.AssetsLocation = &mirrors.AssetLocation{RegistryMirror: "registry.example.com/kops"} // mirror not populated
// after
// stage assets first:
//   kops get assets --copy --asset-file-repository registry.example.com/kops
assetBuilder.AssetsLocation = &mirrors.AssetLocation{RegistryMirror: "registry.example.com/kops"}

// pre-flight: check every image in the manifest is parseable
for _, img := range manifestImages(manifestYAML) {
	if _, _, err := image.ParseNormalizedNamed(img); err != nil {
		return fmt.Errorf("unparseable image %q: %w", img, err)
	}
}

func hasRemappableObjects(objects api.YAMLObjects) bool { return len(objects.Items) > 0 }

objects, err := assetBuilder.RemapManifest(manifestYAML)
if err != nil {
	if strings.Contains(err.Error(), "error remapping images:") {
		cause := strings.TrimPrefix(err.Error(), "error remapping images: ")
		return fmt.Errorf("manifest image remap failed, root cause: %s", cause)
	}
	return err
}

When it happens

Trigger: Calling RemapManifest on a manifest whose objects contain images that fail remapping — e.g. RemapImage returns an error for an unparseable image reference, or hash lookup/download fails for an image while building an addon/cluster manifest.

Common situations: Staging assets with a misconfigured --assets-location; addon manifests referencing images unavailable in a private registry; malformed image names in manifests; network failures downloading image hashes.

Related errors

• error parsing addons or manifest: %v
• failed to parse objects: %w
• failed to parse objects: %w
• failed to parse apiVersion %q
• failed to find kind in object

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