Troubleshoot
Troubleshooting guides are grouped by the part of the cluster where the problem starts. If you know the symptom, jump to its subsystem below. If you don't, start with diagnostics.
Start with diagnostics​
If you don't know where the problem is yet, collect evidence first. The guides in the Diagnostics group narrow most problems down to one of the subsystems that follow.
- Validate your kubecontext to confirm whether you're connected to the cluster or to the control plane cluster.
- Retrieve the deployed vCluster configuration to check what's running against what you expect.
- Enable debug logging in the control plane to see what the syncer does.
- Capture pprof profiles when the control plane is slow or uses too much CPU or memory.
For where each kind of log lives, see Logging.
Control plane​
The control plane doesn't start, restarts, stops accepting changes, or reports a license error.
- etcd NOSPACE alarm when etcd reports
NOSPACEand the control plane stops accepting changes. - etcd defragmentation timeout when the control plane fails to start because embedded etcd can't defragment in time.
- Pro feature license errors when the control plane crashloops with a
vCluster pro featureerror. - Standalone control plane nodes when a vCluster Standalone node has service, network, join, or resource problems.
Worker nodes​
Nodes that no longer match the cluster's configuration still show up in it.
- Clean obsolete nodes when old nodes remain after you change the node selector.
Network​
DNS lookups fail, or connections through Ingress or a load balancer break.
- CoreDNS DNS timeouts when DNS lookups time out or return
SERVFAIL. - kubectl port-forward and Ingress when
kubectl port-forwardfails with connection upgrade errors. - Ingress conflicts with Rancher when Rancher runs in both the cluster and the control plane cluster.
Storage​
The vCluster pod can't run binaries from its volumes.
- noexec emptyDir volumes when the vCluster pod fails to start with
permission deniedbecause emptyDir volumes are mountednoexec.
Synchronization​
Resources don't appear on the other side, or the syncer reports errors about them.
- Gateway API sync when Gateway API resources emit
RefNotPermitted,SyncError, orSyncWarningevents. - Pods stuck at Ready=False on vCluster versions before v0.37.0, when the cluster runs Kubernetes 1.33 or earlier and the control plane cluster runs 1.34 or later.
- Resource proxy when proxied custom resource requests return 4xx or 5xx errors, hang, or don't appear.
Platform problems​
If the problem is in vCluster Platform rather than in a cluster, see Platform troubleshooting. For problems with templates, quotas, or Stacks in a project, see: