---
title: "Server Won't Start"
description: "Diagnose a server stuck on the Starting up screen, read container logs, and recover from a failed startup"
source_url: https://ai-ops.com/docs/troubleshoot/server-startup
---

# 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.

> [!NOTE] 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:

```bash
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:

```bash
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.

```bash
docker logs --tail 200 koios
```

To watch it live while it retries:

```bash
docker logs -f koios
```

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

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

> [!TIP] 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:

```text
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.

> [!CAUTION] 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](https://ai-ops.com/docs/system/backup.md) and [Upgrading Koios](https://ai-ops.com/docs/updates/general.md).

### The machine is out of resources

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

```bash
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:

```bash
sudo systemctl restart docker.koios
```

If Koios was started manually rather than as a service, see [Manually Starting Koios](https://ai-ops.com/docs/installation/manually-starting-koios.md). Watch the logs as it comes back up:

```bash
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:

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

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

## What's Next

- [Logs](https://ai-ops.com/docs/system/logs.md): stream service logs and browse archived log files once the server is running
- [Services](https://ai-ops.com/docs/system/services.md): view and control individual service status
- [Backup & Restore](https://ai-ops.com/docs/system/backup.md): restore from a backup if a startup issue can't be resolved