kubernetes/kops · error

unable to remap CNI plugin binaries asset: %v

Error message

unable to remap CNI plugin binaries asset: %v

What it means

After parsing the env-var-provided CNI URL and hash, FindCNIAssets calls assetBuilder.RemapFile(u, h), which resolves the asset — including rewriting it to a mirror/CDN and computing/validating its hash when building the cluster manifest. This error is thrown when RemapFile fails, typically because the URL can't be fetched (HTTP error, network issue, DNS failure) or the downloaded content's hash doesn't match CNI_ASSET_HASH_STRING.

Source

Thrown at pkg/nodemodel/wellknownassets/cni.go:75

	cniAssetHash := os.Getenv(ENV_VAR_CNI_ASSET_HASH)

	if cniAssetURL != "" && cniAssetHash != "" {
		klog.V(2).Infof("Using CNI asset URL %q, as set in %s", cniAssetURL, ENV_VAR_CNI_ASSET_URL)
		klog.V(2).Infof("Using CNI asset hash %q, as set in %s", cniAssetHash, ENV_VAR_CNI_ASSET_HASH)

		u, err := url.Parse(cniAssetURL)
		if err != nil {
			return nil, fmt.Errorf("unable to parse CNI plugin binaries asset URL %q: %v", cniAssetURL, err)
		}

		h, err := hashing.FromString(cniAssetHash)
		if err != nil {
			return nil, fmt.Errorf("unable to parse CNI plugin binaries asset hash %q: %v", cniAssetHash, err)
		}

		asset, err := assetBuilder.RemapFile(u, h)
		if err != nil {
			return nil, fmt.Errorf("unable to remap CNI plugin binaries asset: %v", err)
		}

		return asset, nil
	}

	switch arch {
	case architectures.ArchitectureAmd64:
		switch {
		case ig.KubernetesVersion().IsGTE("1.36"):
			cniAssetURL = defaultCNIAssetAmd64K8s_36
		case ig.KubernetesVersion().IsGTE("1.35"):
			cniAssetURL = defaultCNIAssetAmd64K8s_35
		case ig.KubernetesVersion().IsGTE("1.34"):
			cniAssetURL = defaultCNIAssetAmd64K8s_34
		case ig.KubernetesVersion().IsGTE("1.32"):
			cniAssetURL = defaultCNIAssetAmd64K8s_32
		}
	case architectures.ArchitectureArm64:

View on GitHub (pinned to 4c8573c808)

Solutions

1. Open the CNI_VERSION_URL in a browser or `curl -I` it to confirm the asset exists and is reachable from the build machine
2. Recompute the checksum (`curl -L <url> | sha256sum`) and update CNI_ASSET_HASH_STRING to match, keeping the "sha256:" prefix
3. Ensure the URL and hash correspond to the same file and CPU architecture (amd64 vs arm64)
4. Fix network/proxy access (set HTTPS_PROXY, whitelist the host) or use an internal mirror URL you control
5. Unset both env vars to use kOps' built-in default CNI assets

Example fix

// before
export CNI_VERSION_URL="https://dist.example.com/cni-plugins-v1.6.2.tgz" # 404
// after
export CNI_VERSION_URL="https://github.com/containernetworking/plugins/releases/download/v1.6.2/cni-plugins-linux-amd64-v1.6.2.tgz"
export CNI_ASSET_HASH_STRING="sha256:<hash of that exact file>"

resp, err := http.Head(os.Getenv("CNI_VERSION_URL"))
if err != nil || resp.StatusCode != http.StatusOK {
    return fmt.Errorf("CNI_VERSION_URL not reachable: %v", err)
}

asset, err := FindCNIAssets(ig, assetBuilder, arch)
if err != nil {
    if strings.Contains(err.Error(), "unable to remap CNI plugin binaries asset") {
        klog.Errorf("CNI override unreachable or hash mismatch; verify URL and CNI_ASSET_HASH_STRING: %v", err)
    }
    return err
}

When it happens

Trigger: Both CNI_VERSION_URL and CNI_ASSET_HASH_STRING are set and assetBuilder.RemapFile(u, h) returns an error during BuildKubernetesFileAssets — e.g. the override URL 404s, the host is unreachable, or the hash of the remote file disagrees with the provided hash.

Common situations: CNI_VERSION_URL points to a deleted/moved GitHub release asset; a corporate proxy or air-gapped network blocks the download; the hash was computed for a different file/arch than the URL points to; typo swapping amd64 and arm64 URLs/hashes.

Related errors

• unable to parse CNI plugin binaries asset URL %q: %v
• unable to parse CNI plugin binaries asset hash %q: %v
• unknown arch for CNI plugin binaries asset: %s
• unknown CNI plugin binaries asset: %s
• error creating kops config template: %w

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