Troubleshooting
Start with what is not running and why:
kubectl -n excalibase-platform get pods
kubectl -n excalibase-platform logs deploy/provisioning --tail=100
kubectl -n excalibase-platform logs job/platform-bootstrap
docker compose ps # single host
docker compose logs provisioning --tail=100
Install
helm install times out, auth and graphql in CreateContainerConfigError. They wait for the
Secret the bootstrap Job writes after the install. Do not pass --wait to the first install; wait
for job/platform-bootstrap instead.
A pod stuck in Init:0/N. Each pod waits for what it depends on (platform database, NATS,
provisioning, auth). kubectl logs <pod> -c wait-for-<name> says which one is missing.
The bootstrap Job fails or runs out of time. Read its log. It needs the control plane healthy;
raise bootstrap.timeoutSeconds on slow nodes and run helm upgrade again.
preflight refuses to start (single host). A secret in .env is weak, short or reused;
docker compose logs preflight names it. Run init.sh on a fresh directory rather than editing
secrets by hand.
Chart render errors such as auth.edge.podCIDRs is required or vault.unseal.awskms.keyArn is required: the chart has no guessed default for these. Set them (see
Configuration).
Networking
Projects are not isolated, or apps cannot be reached. The CNI does not enforce NetworkPolicy
(plain flannel, minikube's default network). Everything installs and nothing is fenced; apps' fences
are CiliumNetworkPolicies and need Cilium. Check with kubectl -n kube-system get ds cilium.
Studio or the API answers 404 from HAProxy. The host name does not match ingress.host /
ingress.admin.host, or DNS points elsewhere. kubectl -n excalibase-platform get ingress lists the
names served.
Requests fail from inside the cluster but work from your browser (apps or functions calling your API, or a waited deploy). Pods must resolve your public names to the edge, as DNS does outside. With Cilium's kube-proxy replacement, host ports work from pods; otherwise resolve the names to the ingress Service in CoreDNS.
Certificates
A certificate stays not ready. kubectl describe certificate -A and kubectl describe challenge -A
give the reason. HTTP-01 needs port 80 reachable from the internet and the DNS name pointing at
your nodes; from inside the cluster, cert-manager's self-check must reach the same address. Try
Let's Encrypt staging first to stay clear of its rate limits (50 new certificates per registered
domain per week; each new app host takes one unless you use a wildcard).
The browser warns on localhost (single host). The edge signs localhost with its own CA.
Accept the warning for a trial, or trust that CA:
docker compose cp edge:/data/caddy/pki/authorities/local/root.crt excalibase-local-ca.crt, then
import it into your browser or pass --cacert excalibase-local-ca.crt to curl.
Databases
A new project stays in WAITING_FOR_READY or PROVISIONING. On Kubernetes, look at its
Cluster: kubectl get cluster -A and kubectl -n <namespace> describe cluster. Common causes: no
default StorageClass (the volume stays Pending), not enough CPU or memory for the tier on any
node, or the CloudNativePG operator not running.
not enough capacity right now. The tier asks for more than the nodes have left. Add capacity, or lower the tier's size as a platform admin.
A paid tier is refused with a node count. It runs one instance per node: 3 instances need 3 schedulable nodes. On a single host, tiers with more than one instance are always refused.
An image pinned by digest only is refused. CloudNativePG needs a tag in imageName
(postgres:17.6@sha256:..., not postgres@sha256:...). Keep a tag in front of every digest you
set.
Sign-up answers 503. No email provider is configured: only the first admin can sign in. Set one (see Configuration).
The control plane does not start after setting SMTP. A setting is malformed: no host, an
unknown TLS mode, a password with tls: none, or a CA it cannot read. The log names it.
Sign-up says the verification email could not be sent. The relay refused: no STARTTLS while
starttls is set, a certificate it cannot verify (give the CA with email.smtp.caSecret), or a
wrong user or password. The control plane's log has the relay's answer.
Vault
Studio redirects to /setup, auth is not ready, projects answer errors. The vault is sealed:
with manual unseal it is sealed after every restart. Sign in as a platform admin and paste the key,
or run excalibase-provisioning vault unseal in the provisioning container. With AWS KMS the
control plane will not start when it cannot decrypt the key: check the key and the credential's
kms:Decrypt permission.
Apps
invalid image reference: must name an explicit tag or digest. Name a tag
(traefik/whoami:v1.11.0) or a digest.
app hosting: the engine has no "runsc" runtime (single host). gVisor is not installed: install
it, or knowingly choose APP_SANDBOX_RUNTIME=none.
A deploy fails on Kubernetes with no node can run runtime class "gvisor". No node matches the
RuntimeClass's node selector (excalibase.io/gvisor=true in the
Kubernetes guide), or no labelled node
has room.
An app's URL shows "This app is not running" (single host). No copy is ready: the app is paused, still rolling out, or its deploy failed. Studio's deploy list shows the reason and the app's logs.