Troubleshooting

Kylth’s own log explains most problems:

docker logs kylth

Installation

The installer’s errors start with kylth:.

“run this as root”

• Fix: run it with sudo bash install.sh.

“Kylth runs on x86_64 servers; this one is …”

• Cause: the server is ARM or another architecture. Kylth supports only x86_64.
• Fix: use an x86_64 server.

Docker is missing or not running

The installer says one of:

• “Docker is not installed. Install Docker Engine first”
• “Docker is installed but its daemon is not reachable. Start it: systemctl start docker”
• “the Docker Compose plugin is missing. Install docker-compose-plugin.”

Fix: install or start what’s named, following Docker’s install guide, then run the installer again.

“ports 80 and 443 must be free”

• Cause: another web server is using port 80 or 443.
• Check: ss -ltnp | grep -E ':(80|443) '
• Fix: stop that service or move it to other ports, then run the installer again.

“Kylth is already installed here (/etc/kylth)”

• Cause: Kylth is already installed.
• Fix: to move to a newer version, see Upgrade.

“Kylth did not become healthy within three minutes”

• Cause: Kylth started but then stopped, and the installer printed its log just above this message.
• Fix: find the message in that log in the Dashboard section below.

Dashboard

Kylth keeps restarting, and the dashboard is down

Check: docker ps --filter name=kylth shows kylth restarting. Then docker logs kylth shows one of these:

“Kylth cannot start: set KYLTH_DOMAIN, KYLTH_BASE_DOMAIN”

• Cause: a required setting is missing in /etc/kylth/.env. The message lists only the ones missing.
• Fix: add them, as described in Settings, then run docker compose up -d in /etc/kylth.

“Kylth cannot start: the Docker daemon does not see these folders at the same path Kylth does”

• Cause: a folder in docker-compose.yml is mounted at a different path inside the container. The message names it.
• Fix: make each volume read /path:/path, with the same path on both sides. Security & permissions explains why.

If the message instead says “the Docker daemon could not run the check container”, Docker couldn’t start the short-lived container Kylth uses for this check. Docker’s reason follows.

“Kylth could not start Caddy”

• Cause: port 80 or 443 is taken, or another container is already named kylth-caddy.
• Fix: free the port, or remove or rename that container. The message ends with Docker’s own error.

The dashboard doesn’t load

• Check: is kylth running and healthy? Run docker ps --filter name=kylth.
• If it is, the problem is DNS or the certificate. See DNS & HTTPS.

Can’t sign in

• Forgotten password: use the password-reset link on the sign-in page. Kylth can only email the link if SMTP is set up, under Settings → Notifications.
• No email set up: an administrator can reset the password for you from within Kylth.

DNS & HTTPS

A name doesn’t resolve

• Check: dig +short app.example.com should print the server’s IP address.
• Fix: correct the record at your DNS provider, and allow time for the change to spread. See DNS setup.

Projects’ addresses don’t resolve

• Cause: the wildcard record is missing or misnamed.
• Check: dig +short anything.projects.example.com should print the server’s IP address.
• Fix: the record’s name must be *.projects.example.com, or *.projects with providers that add your domain themselves.

The browser shows a certificate warning

• Cause: Let’s Encrypt couldn’t reach the server on ports 80 and 443, or the name doesn’t yet point at the server.
• Check: docker logs kylth-caddy. Look for “could not get certificate”, and the reason after it.
• Fix: open ports 80 and 443 to the internet, correct the DNS, and remove any proxy in front of the server. Caddy retries by itself, so there’s nothing to restart.

Projects

“Create project” is greyed out

• Cause: every running slot is in use. Hovering the button shows how many there are.
• Fix: stop a project you don’t need, or raise the maximum under Settings → Resources. Check the server has the memory first; see Requirements.

A project doesn’t start, or shows as unhealthy

• Check: the project’s page shows its status. Its Resources tab and free -h show whether the server is short of memory.
• Check: docker ps --filter name=<project> lists the project’s containers and their health.
• Fix: if the server is short of memory, stop other projects or add memory. Otherwise, docker logs kylth shows the reason.

A project’s address doesn’t work

• Check: the project is running, its name resolves (see DNS & HTTPS), and its certificate was issued.

Studio asks for a username and password

That’s expected. They’re DASHBOARD_USERNAME and DASHBOARD_PASSWORD, on the project’s Overview tab under Credentials.

Backups

A backup failed

• Check: in the project’s Backups tab, the failed backup shows its error beneath it. docker logs kylth records it as backup <id> failed.
• Common causes: the disk is full (check df -h), or the destination is unreachable or its credentials are wrong.
• Fix: free space, or correct the destination under Settings → Backups.

A restore failed

• Check: the project’s Backups tab lists restores and their status, and docker logs kylth has the detail.

Licensing

The licence is rejected

Kylth says why when you install it:

You’ve reached a limit

Kylth says which limit, for example: “The Free tier allows 1 user.” Install a licence, or a plan with higher limits. Everything that already exists keeps working. See Licence.

The licence expired

After the 14-day grace period, the Free tier applies. Download the renewed licence from manager.kylth.com and install it under Settings → Licence. See Licence.

Kylth shows the Free tier, but you have a licence

• Cause: the licence file is missing from /opt/kylth/licenses/, for example after restoring the server without that folder.
• Fix: install the licence again under Settings → Licence.