kubernetes/kops · error

failed to load package: %w

Error message

failed to load package: %w

What it means

The wellknownoperators Builder.Build walks cluster objects and, for ClusterPackage objects in the addons.x-k8s.io group, loads the package from its manifest. If loadClusterPackage fails (unreadable/invalid package source), the error is wrapped with "failed to load package" and model building aborts. It indicates the ClusterPackage resource references something the builder cannot resolve or parse.

Source

Thrown at pkg/wellknownoperators/operators.go:62

	if !featureflag.UseAddonOperators.Enabled() {
		return nil, objects, nil
	}

	var packages []*Package
	var keepObjects kubemanifest.ObjectList

	for _, object := range objects {
		keep := true

		// We may in future move ClusterPackage to the server-side,
		// however remapping it client-side allow us to use our existing manifest logic
		// including image remapping.
		if object.Kind() == "ClusterPackage" {
			u := object.ToUnstructured()
			if u.GroupVersionKind().Group == "addons.x-k8s.io" {
				pkg, err := b.loadClusterPackage(u)
				if err != nil {
					return nil, nil, fmt.Errorf("failed to load package: %w", err)
				}
				packages = append(packages, pkg)
				keep = false
			}
		}

		if keep {
			keepObjects = append(keepObjects, object)
		}
	}
	return packages, keepObjects, nil
}

func (b *Builder) loadClusterPackage(u *unstructured.Unstructured) (*Package, error) {
	operatorKey := u.GetName()
	if operatorKey == "" {
		return nil, fmt.Errorf("could not get name from ClusterPackage")
	}

View on GitHub (pinned to 4c8573c808)

Solutions

  1. Inspect the ClusterPackage object (kops get clusterpackages / the addon manifest) and verify spec.source points to a reachable, valid package manifest
  2. Ensure the package manifest has a valid name (metadata.name) and spec.version
  3. Fix or remove the offending ClusterPackage from the cluster spec and re-run kops update cluster
  4. Upgrade/align kops and the addon to compatible versions if the schema changed

Example fix

// before
spec:
  version: ""        # empty -> loadClusterPackage fails
  source: https://example.com/missing-manifest.yaml
// after
spec:
  version: "1.0.0"
  source: https://example.com/valid-manifest.yaml
Defensive patterns

Strategy: validation

Validate before calling

for _, obj := range objects {
    if obj.Kind() == "ClusterPackage" && obj.GroupVersionKind().Group == "addons.x-k8s.io" {
        if obj.GetName() == "" {
            return fmt.Errorf("ClusterPackage without name in cluster spec")
        }
        ver, found, _ := unstructured.NestedString(obj.Object, "spec", "version")
        if !found || ver == "" {
            return fmt.Errorf("ClusterPackage %s missing spec.version", obj.GetName())
        }
    }
}

Try / catch

pkgs, keep, err := b.Build(ctx, objects, cluster, ...
if err != nil {
    if strings.Contains(err.Error(), "failed to load package") {
        return fmt.Errorf("fix or remove the offending ClusterPackage: %w", err)
    }
    return err
}

Prevention

When it happens

Trigger: b.loadClusterPackage(u) returns an error for a ClusterPackage object encountered during Build — bad spec.source, missing manifest, or nested load errors (e.g. could not get name/spec.version).

Common situations: A ClusterPackage added via kops create/apply with a wrong or unreachable source URL; manifest missing required metadata (name or spec.version empty — see errors 1789 and its sibling); addon manifests edited by hand; version skew between kops and the package spec schema.

Related errors

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