Server Won't Start

Two symptoms bring you here, and both mean the same thing: the interface is running but the server behind it is not answering.

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.

If you are already signed in and working when a red bar appears at the bottom of the app reading "Cannot reach the Koios server. Data shown may be out of date.", the server has become unreachable while your session was open. Everything on screen is the last data that arrived — treat it as a snapshot, not live values.

You do not need to reload. Koios keeps checking the server's health in the background and refreshes the page's data as soon as it answers. If you dismiss the banner and the server drops again later, it comes back.

Other alerts are hidden while this is active

Every other system alert is reported by the server, so none of them can be trusted while it is unreachable — Koios suppresses them all and shows only this banner. A license or failed-entity alert vanishing during an outage does not mean it was resolved. Wait for the server to return, then re-read the alerts panel.

If the banner does not clear within a minute or two, work through the same steps below.

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, and an open session clears its Server Unreachable banner and refreshes on its own — there's no need to reload either one.

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