Troubleshooting

Start with the branch’s conditions and events; they name the problem in one line.

kubectl -n skela get branches
kubectl -n skela describe branch <name>        # conditions and recent events
kubectl -n skela logs deploy/skela-control | tail -50

The console shows the same conditions on the branch, and the API returns them as conditions on every branch.

Installation

Message	Fix
release.env not found	Run the installer from the extracted bundle, or set SKELA_RELEASE_ENV to the file’s path.
images must be repository@sha256:...	An image variable holds a tag. Use the digests from release.env, or the same digests in your mirror.
set SKELA_TLS_ISSUER ..., Issuer ... does not exist	Install cert-manager and create the issuer first; a namespaced Issuer must be in skela (the installer creates the namespace on the first run and stops).
cert-manager is not installed	Install cert-manager in the target cluster.
SKELA_LICENSE_KEY is required	Export your key and rerun. See licensing.md.
SKELA_LICENSE_KEY is not a SkelaDB license key	The value is truncated or has extra characters. It is one line, <payload>.<signature>.
StorageClass ... does not exist, skela-gp3 needs the EBS CSI driver	Install the CSI driver or name an existing class.
SKELA_..._IMAGE is missing	The release.env is not the one shipped with this release, or a variable overrode it with an empty value. Use the release’s release.env.
SKELA_TLS_CA_SECRET needs SKELA_STORAGE_MODE=pvc	A separate CA bundle works for dedicated disks only. Use an issuer that writes ca.crt for object storage, or set SKELA_STORAGE_MODE=pvc.
PostgreSQL N is not in this release	0.0.1 ships PostgreSQL 18 only.
Controller exits at startup naming a setting	The message names the variable; the controller checks all settings before it touches the cluster. An invalid license key also stops it.
Storage services exit with a conditional write error	Your object store ignores If-None-Match or If-Match. Use a store that supports conditional writes.

Branch states

Condition	Meaning and fix
Ready=False, Starting	Normal while the compute starts.
Ready=False, ReconcileError	The last two attempts failed; the message has the error. Common causes: missing project identity (skela-branch-<project> and skela-backup-<project>), a refused license, capacity limits.
Failed, ComputeUnavailable	The compute container cannot start: image pull, crash loop or configuration. The message names the container and its last error. Check pull secrets and node capacity.
Failed, ComputeProtocolMismatch	The PostgreSQL image and the controller come from different releases. Use the images from one release.env. No data was touched.
Failed, RestoreTargetUnreachable	The requested restore time is after the last archived WAL. Delete the branch and restore to an earlier time.
StorageResized=False, ExpansionUnsupported	The StorageClass does not allow volume expansion. The branch keeps running on its current disk.
StorageResized=False, FileSystemResizePending	The disk grew; the filesystem grows when the node supports it, otherwise at the next suspend and wake.
ImageCurrent=False, RolloutPending	Waiting its turn for a new PostgreSQL image after an upgrade.
BackupsPurged=False, PurgeFailed	Deleting the branch’s backups failed three times; the last Job’s log says why (often bucket permissions). Fix it, then set the annotation skeladb.io/purge-retry to a new value to try again.

A Failed branch keeps its data and leaves Failed as soon as the compute becomes ready.

License refusals

New branches are refused with HTTP 402, and console operations fail, when no key is installed, the key has expired, or the branch or project limit is reached. Running databases are never stopped by the license. The controller logs the reason at startup and the metrics skela_license_valid and skela_license_expiry_timestamp show the key’s state. Install or renew the key as in licensing.md.

Connections

Error	Meaning
28P01	Wrong password, unknown role, or a role whose password is not SCRAM-SHA-256. The proxy does not say which.
Login waits, then 08001	The branch could not be woken or reached within 30 seconds. Check the branch’s conditions and that the controller is running.
53300	A proxy admission limit was reached. Add proxy replicas or reduce idle connections.
Logins refused after repeated failures	Login backoff for that address and role; it clears within five minutes.
server certificate does not match host name	Connect to the name in SKELA_TLS_DNS_NAME, and give the client your issuer’s CA.
Connection closed at once from some addresses	The branch’s network access list does not include the client, or the load balancer hides client addresses.
A suspended branch keeps waking up	Something is connecting: a health check, a pooler or a scheduled job. Repeated failed logins from one address are throttled and cannot keep it awake.

Console

Symptom	Fix
Console exits at startup with a list	Each line names a setting in console-config to fix.
/readyz returns 503	The console cannot reach the API: check SKELA_CLOUD_API_URL and the cloud-api pods.
API or worker refuses to start: schema is older than this release	Run the release’s migration: cloud/render.sh apply.
API refuses to start: a migration’s checksum changed	The database was migrated by a different build of the same version. Use the published images.
“Ask your SkelaDB admin to allow your account to create organizations”	Add the user, their email or @domain to SKELA_CLOUD_ORG_CREATORS, or have an operator create the organization and invite them.
Signed out unexpectedly	Idle timeout (SKELA_CONSOLE_IDLE_MINUTES, default 60) or, for operators, the 30-minute session cap.
A request fails once with 503 after a database failover	Expected: each stale pooled connection fails one request and is replaced.
Project creation fails or waits	The worker retries for about 30 minutes; the operation shows the error. Usual causes: no free slot in the region, a refused license, or the region’s controller unreachable.
Imports from a public database fail to connect	Set SKELA_CLOUD_PUBLIC_IMPORTS=1 when rendering the console.
Stored credentials unreadable after a restore	The encryption key that sealed them is missing. Run cloud/render.sh check-keys and restore the key from escrow.

Every console and API log line carries a request_id, also returned to the browser as X-Request-Id; search both logs for it.

Getting help

Collect the release version, kubectl -n skela describe branch <name>, the controller log around the problem and the request ID, and contact support through the channel in your agreement. Report security problems to security@skeladb.com.