Skip to main content

🚑 Common Issues & Fixes

Even the best-orchestrated fleets hit a snag. This guide provides human-friendly solutions for common hurdles you might encounter while using LaraKube CLI.

🔒 HTTPS / Trust Issues (Start Here)​

Symptom: Your browser shows a security warning, a .kube domain won't load over HTTPS, or you see certificate errors in the console.

First diagnostic to run:

larakube trust:check

trust:check probes the entire local HTTPS trust chain — CA files in ~/.larakube/certificates/, keychain trust, live DNS resolution for .kube domains, system cert validity, and per-app cert validity — and tells you exactly which step is broken. It returns exit code 1 if any issues are found.

Common fixes based on trust:check output:

  • CA not trusted in keychain: run larakube trust to install it.
  • DNS not resolving: run larakube hosts (and ensure dnsmasq is running as a root daemon on macOS — see macOS setup).
  • CA files missing or corrupted: run larakube trust:reset to destroy and regenerate the local CA. Per-app certs regenerate automatically on the next larakube up.

📁 Unreachable Projects​

Symptom: The LaraKube Console displays a "Source path unreachable" warning or fails to sync with a project.

The Cause: This usually happens when the LaraKube Console is running in a different environment or context than where the project was created, or if the project's workspace mount has moved on your host machine.

The Fix:

  1. Verify Mounts: Ensure your host machine's code directory is correctly mounted to the LaraKube CLI Docker daemon.
  2. Align Paths: The Console and CLI must agree on where your projects live. If you've moved your project folder, run larakube doctor inside the project directory to re-align the metadata.
  3. Console Refresh: Click the "Re-scan Projects" button in the Console settings to update its internal path registry.

🔌 Traefik Networking Issues​

Symptom: You can't access https://traefik.kube or your project's .kube domain.

The Fix:

  1. Run trust:check: larakube trust:check identifies whether the problem is the CA, DNS, or the cert itself.
  2. Trust the CA: Ensure you have run larakube trust. This installs the local SSL authority required for valid HTTPS.
  3. Check Traefik Status: Check the console health or use larakube about and verify the traefik pod is in a Running state.
  4. Restart Traefik: If networking feels "stuck," run larakube traefik:restart to perform a graceful rollout.

💾 Volume & Persistence Issues​

Symptom: A database pod is stuck in a Pending state with an error like FailedScheduling or volume errors.

The Fix:

  1. Recreate Strategy: LaraKube CLI uses a Recreate strategy for databases to prevent volume corruption. Ensure you aren't trying to run multiple instances of the same database on the same volume.
  2. Purge & Heal: If a volume is truly corrupted, you can run larakube purge followed by larakube heal to reset the manifests and attempt a fresh mount.

A specific case: pod has unbound immediate PersistentVolumeClaims​

Symptom: kubectl describe pod (or larakube output) for a database/storage pod shows:

Warning  FailedScheduling  ...  0/1 nodes are available: pod has unbound immediate PersistentVolumeClaims. not found

The Cause: Every driver-managed local service (Postgres, MySQL, MariaDB, MinIO, SeaweedFS, Garage, Meilisearch, Typesense) gets its own statically-named PersistentVolume, bound to a fixed host path under .infrastructure/volume_data/, with a Retain reclaim policy. Retain means deleting the PersistentVolumeClaim (e.g. when plex:join/plex:migrate tears the self-hosted service down, or plex:leave brings it back) does not delete the underlying PersistentVolume — it just marks it Released. A Released PV can't automatically rebind to a brand new PVC, so the freshly re-applied PVC just sits there unbound and the pod can never schedule.

You can confirm this is what's happening:

kubectl get pv | grep <your-app-name>

If a PV shows Released in the STATUS column, that's it.

The Fix: Nothing manual needed — larakube up detects a Released (or otherwise stale) driver-managed PV and deletes it automatically before applying, so a fresh, bindable PV takes its place. The underlying data is never at risk: Retain means deleting the PV object itself doesn't touch the host path it pointed at. Just re-run:

larakube up

This comes up most often right after plex:join, plex:migrate, or plex:leave — anything that tears a self-hosted service's PVC down and later brings the service back.

🔐 OpenBao Sealed — Secrets Stop Syncing After a k3s Restart​

Symptom: A tool that reads secrets from OpenBao (Forgejo, Stalwart, Vaultwarden, Zitadel, …) fails to start, or kubectl get externalsecret -A shows Ready: False with could not get secret data from provider or ClusterSecretStore "openbao" is not ready. kubectl get pods for openbao-backend still shows 1/1 Running — its readiness probe deliberately treats "sealed" as healthy (so it doesn't crashloop while waiting on a human), so the pod looks fine even though it's not serving secrets.

The Cause: OpenBao (Shamir seal) reseals itself on every restart of its pod — that's inherent to how it works, not a malfunction. On a cloud/production cluster this is deliberate (SecretsInitCommand.php): auto-unseal only works by storing the unseal key in a Secret next to OpenBao, which would defeat the point of sealing on a cluster a human isn't watching 24/7 — local dev gets auto-unseal (a laptop sleep/wake cycle is the problem it solves there), production doesn't.

What actually restarts the openbao-backend pod on a cloud cluster is usually not a VM reboot — it's systemctl restart k3s, which two LaraKube CLI commands run deliberately and warn about before doing:

  • larakube dashboard:trust (writes OIDC trust into /etc/rancher/k3s/config.yaml, then restarts k3s to apply it)
  • larakube cluster:setup

Restarting k3s restarts its embedded containerd too, which kills and restarts every pod on the node simultaneously — not just OpenBao. If you just ran either of those commands and things look broken cluster-wide a moment later, this is almost certainly why.

The Fix:

larakube secrets:unseal <environment>

This unseals OpenBao using the key already stored in-cluster (the openbao-bootstrap Secret in larakube-secrets, written once by secrets:init) — no manual key handling required.

If ExternalSecrets are still showing a stale failed condition a minute after unsealing (the ClusterSecretStore and per-tool ExternalSecret resources cache their own validation state and don't always re-check immediately), force a re-check:

kubectl annotate clustersecretstore openbao force-sync=$(date +%s) --overwrite
kubectl annotate externalsecret <name> -n <namespace> force-sync=$(date +%s) --overwrite

Or simply re-run the affected tool's :init command (e.g. larakube git:init <environment>) — most :init commands already wait for their ExternalSecret to report a fresh sync before finishing.

To avoid getting caught out again: after running dashboard:trust or cluster:setup on a cluster that has secrets:init deployed, make larakube secrets:unseal <environment> a habit — right after, not whenever someone happens to notice something else is broken.

🚀 Vite / HMR Issues​

Symptom: Your frontend changes aren't reflecting, or you see Vite connection errors in the browser console.

The Fix:

  1. Harden Config: Ensure your vite.config.js has been "hardened" by LaraKube CLI. You can manually trigger this by running larakube add vite (it will detect and fix existing configs).
  2. Port Alignment: Verify that your WATCH_PORT in .env matches the port defined in your larakube-web service manifests.