Troubleshooting

Common issues, mostly drawn from real cluster bring-up.

A new status field is always empty on-cluster

You changed the VibedApp CRD and helm upgraded, but a new status.* field never persists.

Cause: Helm installs CRDs from crds/ only on first install and never on upgrade, so the live CRD lacks the new field and the apiserver silently strips it from writes.

Fix: apply the CRD by hand.

kubectl apply -f deploy/helm/vibed/crds/vibed.dev_vibedapps.yaml
# verify the field is in the schema:
kubectl get crd vibedapps.vibed.dev -o jsonpath='{.spec.versions[0].schema.openAPIV3Schema.properties.status.properties.<field>}'

Deploy returns Phase=Failed immediately (TemplateMissing / TemplateInvalid)

kubectl get vibedapp <name> -n vibed-apps -o jsonpath='{range .status.conditions[*]}{.type}={.reason}: {.message}{"\n"}{end}'

• TemplateMissing: no SandboxTemplate for template "<slot>": the classifier picked a slot (e.g. go-123, base-al2023) that has no warm pool in this install. The dev overlay ships static-nginx, node-24 and python-313; the heavier slots are opt-in. Enable the one you need:

  make enable-go-pool   # or enable-base-pool

  This failure happens before a pod exists, so there are no logs to read. The reason and message are on the app itself (GET /v1/apps/{id} returns them, and both MCP tools surface them), so check those rather than chasing empty logs. Retrying will not help: it is a configuration gap, not a transient error.

  See Local development → warm pools.

• TemplateInvalid: template "<slot>" image failed validation: the BYO validator marked the warm pool's image as not meeting the agent contract. Two common dev causes: (1) the warm pod hasn't reached Ready yet and the validator recorded "no Ready pod"; restart the controller (kubectl rollout restart -n vibed-system deploy/vibed-controller) to force an immediate re-check rather than waiting for the next 2-minute cycle; (2) the template image is genuinely broken; see the BYO base-image guide for the contract.

App stuck in Starting

kubectl get vibedapp <name> -n vibed-apps -o jsonpath='{range .status.conditions[*]}{.type}={.reason}: {.message}{"\n"}{end}'

• InjectFailed … context deadline exceeded: the sandbox agent couldn't pull the source tarball. The usual cause in dev is a stale storage.tarball.served.publicBaseURL (e.g. a hardcoded Service ClusterIP that changed on reinstall). Leave it empty so it defaults to the Service DNS name. In production, this means served is being used where s3 is required; switch to s3.
• AgentUnreachable: the controller can't reach the sandbox agent on :9000. Check the sandbox NetworkPolicy: Managed mode blocks the control plane. Use runtime.sandboxNetworkPolicy: Unmanaged + networkPolicy.enabled: true.

App is Ready but the URL 502s / isn't reachable

• 502 after a sandbox pod restart: the route follows a per-app Service, and the controller re-injects source on pod recreation, so this self-heals within a reconcile. If it persists, check the Service has endpoints: kubectl get endpoints vibed-app-<label> -n vibed-apps.

• https://<label>.localhost won't open (dev): dev Caddy serves plain HTTP on host port 80 (via kind's extraPortMappings 31080 → 80). Use the URL vibeD actually returns: http://<label>.localhost/ (no port). *.localhost resolves in Chrome/Firefox; in Safari add a /etc/hosts entry or use Chrome.

• Caddy route missing: check vibed-router logs and the Caddy admin API:

  kubectl exec -n vibed-system deploy/vibed-caddy -- wget -qO- http://localhost:2019/config/apps/http/servers

App deployed but not in the dashboard

The dashboard lists apps via /v1/apps. Confirm the API returns it:

curl http://localhost:8080/v1/apps

If it's there but not in the UI, hard-refresh the browser to drop a stale cached bundle. Note that auth scopes the list to the caller's owner; with auth disabled everything is owned by admin.

Warm pool empty / claims time out

kubectl get sandboxwarmpool -n vibed-apps
kubectl get pods -n vibed-apps

• Template image not pullable → warm sandboxes never become Ready. Check the warmPools.<template>.image ref and registry credentials.
• agent-sandbox controller not running → no binding happens. Confirm it's installed and healthy.

Diagnostic commands

Command	Purpose
kubectl get pods -n vibed-system	Control-plane status
kubectl logs -n vibed-system deploy/vibed-controller	Reconcile / claim / inject logs
kubectl logs -n vibed-system deploy/vibed-router	Route programming
kubectl get vibedapp -A	All apps + phase + URL
curl -s localhost:8080/metrics | grep vibed_	Prometheus metrics