Support

Troubleshooting

Recipes for the errors we see most often. Each entry explains the symptom, the underlying cause, and the fix.

Collecting diagnostics

Run the built-in diagnostics bundle before opening an issue. It captures service status, versions, and the last 500 log lines.

bash

$killthehost doctor --bundle diagnostics.tgz

Docker daemon not running

Symptom: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.

Fix:

bash

# Linux
$sudo systemctl enable --now docker
$sudo usermod -aG docker $USER && newgrp docker
# macOS / Windows
$open -a "Docker Desktop"   # macOS
# Windows: launch Docker Desktop from the Start menu
$docker info   # should print server info, not an error

Port 5000 in use

Symptom: The launcher exits with address already in use: :5000 on startup.

Cause: Another process (often macOS AirPlay Receiver or a stale launcher) already holds the panel port.

bash

# Find the listener
$lsof -nP -iTCP:5000 -sTCP:LISTEN
# Either kill it …
$kill -TERM <PID>
# … or override the panel port
$export KTH_PANEL_PORT=5050
$killthehost start

Cloudflare tunnel offline

Symptom: Panel shows tunnel: degraded and public hostnames 502.

1. Check the daemon

bash

$systemctl status cloudflared
$journalctl -u cloudflared -n 200 --no-pager

2. Check the hostname

bash

$cloudflared tunnel info killthehost
$dig +short app.example.com CNAME

The CNAME should resolve to <tunnel-uuid>.cfargotunnel.com. If it doesn't, re-run cloudflared tunnel route dns ….

DNS changes not propagating

Namecheap changes are live within a few minutes, but recursive resolvers may cache the old answer up to the TTL of the previous record.

bash

# Query authoritative directly (bypasses cache)
$dig @ns1.namecheaphosting.com app.example.com A +short
# Compare with a public resolver
$dig @1.1.1.1 app.example.com A +short

If the authoritative answer is correct and the public one is stale, wait for the TTL to expire or flush your local DNS cache.

PHP site returns 502

Symptom: Browser shows 502 Bad Gateway; the nginx access log records upstream prematurely closed.

Check that the PHP-FPM container is running: docker ps | grep php.
Tail the FPM log: docker logs -f php-fpm-8.3.
Increase max_execution_time or memory_limit from PHP-MNGR → php.ini.
Make sure the site's document root matches the path mounted into the container.

Database permission denied

Symptom: permission denied for schema public (Postgres 15+) or Access denied for user (MySQL).

sql

-- Postgres 15+
GRANT ALL ON SCHEMA public TO myuser;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT ALL ON TABLES TO myuser;
-- MySQL
GRANT ALL PRIVILEGES ON mydb.* TO 'myuser'@'%';
FLUSH PRIVILEGES;

Outgoing mail lands in spam

Deliverability is a combination of DNS, content, and reputation.

Publish SPF, DKIM, and DMARC records — MAIL-SRVR prints them in the DNS tab.
Make sure your HELO/rDNS matches the sending hostname.
Send yourself a test through mail-tester.com and aim for a score of 10/10.
Avoid consumer ISPs — many block port 25 entirely. Use a residential VPS or relay through a deliverability service.