kubernetes/kubernetes · error

pod specification (%v): %v

Error message

pod specification (%v): %v

What it means

Thrown by AttemptToLoadRecycler (plugins.go:151) when a custom recycler pod template loaded from a file (PodTemplateFilePathHostPath or PodTemplateFilePathNFS) fails volume.ValidateRecyclerPodTemplate. The recycler is a pod used to wipe reclaimable PVs; the loaded pod spec must meet the recycler contract (correct image, service account, volumes, etc.). The %v placeholders are the file path and the underlying validation error.

Source

Thrown at cmd/kube-controller-manager/app/plugins.go:151

				filteredPlugins = append(filteredPlugins, plugin)
			}
		}
	}

	return filteredPlugins, nil
}

// AttemptToLoadRecycler tries decoding a pod from a filepath for use as a recycler for a volume.
// If successful, this method will set the recycler on the config.
// If unsuccessful, an error is returned. Function is exported for reuse downstream.
func AttemptToLoadRecycler(path string, config *volume.VolumeConfig) error {
	if path != "" {
		recyclerPod, err := volumeutil.LoadPodFromFile(path)
		if err != nil {
			return err
		}
		if err = volume.ValidateRecyclerPodTemplate(recyclerPod); err != nil {
			return fmt.Errorf("pod specification (%v): %v", path, err)
		}
		config.RecyclerPodTemplate = recyclerPod
	}
	return nil
}

View on GitHub (pinned to b882c60b40)

Solutions

1. Inspect the underlying ValidateRecyclerPodTemplate error (the second %v) and fix the pod manifest to satisfy the recycler contract.
2. If you do not need a custom recycler, clear PodTemplateFilePathHostPath/NFS to use volume.NewPersistentVolumeRecyclerPodTemplate default.
3. Validate the pod manifest decodes cleanly with kubectl (e.g. `kubectl apply --dry-run=client -f recycler.yaml`) before pointing KCM at it.

Example fix

// before: points at a non-compliant pod template
config.PersistentVolumeRecyclerConfiguration.PodTemplateFilePathNFS = "/etc/k8s/recycler.yaml"
// after: use the built-in default recycler template
config.PersistentVolumeRecyclerConfiguration.PodTemplateFilePathNFS = ""

// Validate a recycler pod template file before pointing KCM at it
pod, err := volumeutil.LoadPodFromFile(path)
if err != nil {
    return err
}
if err := volume.ValidateRecyclerPodTemplate(pod); err != nil {
    return fmt.Errorf("pod specification (%v): %v", path, err)
}

if err := AttemptToLoadRecycler(path, config); err != nil {
    logger.Error(err, "recycler template invalid; falling back to default")
    config.RecyclerPodTemplate = volume.NewPersistentVolumeRecyclerPodTemplate()
}

When it happens

Trigger: Configuring PersistentVolumeRecyclerConfiguration.PodTemplateFilePath{HostPath,NFS} to point at a JSON/YAML pod manifest that, once decoded, violates ValidateRecyclerPodTemplate (e.g. missing the recycler label, wrong restart policy, incompatible volume mounts).

Common situations: Customizing the volume recycler pod image or settings and providing a malformed template file; upgrading K8s where the recycler pod contract tightened; pointing the path at a stale file from an older cluster.

Related errors

• concurrent-ephemeralvolume-syncs must be greater than 0, but
• concurrent-horizontal-pod-autoscaler-syncs must be greater t
• concurrent-job-syncs must be greater than 0, but got %d
• --service-cluster-ip-range can not contain more than two ent
• built-in cloud providers are disabled. The ipam %s is not av

AI-assisted analysis of kubernetes/kubernetes@b882c60b40 (2026-08-07). Data as JSON: /api/errors/d3db6e020f6f3a06. Report an issue: GitHub.