Skip to main content
Version: main 🚧

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.

  1. Validate your kubecontext to confirm whether you're connected to the cluster or to the control plane cluster.
  2. Retrieve the deployed vCluster configuration to check what's running against what you expect.
  3. Enable debug logging in the control plane to see what the syncer does.
  4. 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.

Worker nodes​

Nodes that no longer match the cluster's configuration still show up in it.

Network​

DNS lookups fail, or connections through Ingress or a load balancer break.

Storage​

The vCluster pod can't run binaries from its volumes.

  • noexec emptyDir volumes when the vCluster pod fails to start with permission denied because emptyDir volumes are mounted noexec.

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, or SyncWarning events.
  • 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: