Server Won't Start

If the sign-in screen shows "Starting up..." and never advances to the login form, the web interface has loaded but the server behind it has not finished starting — or it failed to start.

The page keeps checking in the background and recovers on its own the moment the server is ready, so a slow first start or a large database update can simply take a few minutes. If it stays on this screen longer than that, use the steps below to find out why.

What this screen means

The interface you see is served independently of the application server. Reaching "Starting up..." confirms the machine is reachable and the web layer is running — the part still coming up is the application server that handles logins and data.

Check the container status

Open a terminal on the machine running Koios (or connect to it over SSH), then check whether the container is running or restart-looping:

docker ps

Find the koios container. A healthy server shows a status like Up 2 minutes (healthy). A status that keeps resetting to Restarting, or shows (unhealthy), means startup is failing repeatedly.

If Koios runs as a service, check it directly:

sudo systemctl status docker.koios

Read the startup logs

The container's log stream shows the startup sequence — applying database updates, seeding, then starting services. This is where a failed start reports why.

docker logs --tail 200 koios

To watch it live while it retries:

docker logs -f koios

To read a specific service's log file inside the container:

docker exec koios tail -n 200 /var/www/koios/logs/services/django.log

What to look for

Scroll to the end of the output and read upward to the first error or traceback. The last error before the container exits or restarts is almost always the real cause.

Common causes

A database update failed

On startup Koios applies any pending updates to the configuration database before it begins serving. If one fails, the server stops before the login screen is available and the container restarts, retrying the same failing step.

The log shows the update step that failed followed by an error. Capture the full error and contact support. Do not delete data or force the container past this step — that can leave the database in an inconsistent state.

Schema version incompatible

If you recently changed the Koios version, the startup log may show:

FATAL: Schema version incompatible

This happens when a newer version of Koios previously upgraded the database, and an older version is now trying to run against it. The older version cannot safely read the upgraded database, so it refuses to start.

Downgrades are not supported

Once a version has upgraded the database, you cannot run an older version against it. To recover, run the newer version again, or restore a backup taken before the upgrade. See Backup & Restore and Upgrading Koios.

The machine is out of resources

A full disk or exhausted memory can stall startup. Check available space:

df -h

If the volume holding Koios data is full, free up space or expand the disk, then restart.

Restart the server

After addressing the cause, restart Koios:

sudo systemctl restart docker.koios

If Koios was started manually rather than as a service, see Manually Starting Koios. Watch the logs as it comes back up:

docker logs -f koios

The "Starting up..." screen advances to the login form automatically once the server is ready — there's no need to reload.

Still stuck?

If the server keeps failing after a restart, capture the startup logs and contact support:

docker logs --tail 500 koios > koios-startup.log

Attach koios-startup.log so the cause can be diagnosed quickly.

What's Next

Logs: stream service logs and browse archived log files once the server is running
Services: view and control individual service status
Backup & Restore: restore from a backup if a startup issue can't be resolved

Licensing Problems Collecting Diagnostics for Support