---
title: "If the Install Goes Wrong"
description: "Symptoms, causes and fixes for the problems that come up while installing Koios"
source_url: https://ai-ops.com/docs/installation/install-troubleshooting
---

# If the Install Goes Wrong

The failures that actually come up during installation, with the cause and the fix for each. They are grouped by where you were when it happened.

If Koios installed successfully and later stopped working, [Server Won't Start](https://ai-ops.com/docs/troubleshoot/server-startup.md) covers that instead.

## Quick Reference

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Virtual machine shows a boot menu instead of the Ubuntu installer | Secure Boot is rejecting the installer | [Turn off Secure Boot](https://ai-ops.com/docs/installation/hyper-v.md#step-4-turn-off-secure-boot) |
| No network address during the Ubuntu install | Adapter on the wrong virtual switch | Use an **External** switch on Hyper-V, or bridged elsewhere |
| Machine unreachable after install, address looks right | Machine's address typed into the installer's Subnet field | [Correct it](#the-address-set-during-install-does-not-work) |
| `ssh` refused after install | OpenSSH server not installed | Install it at the console, then reconnect |
| `netplan apply` reports an error | Indentation, or a wrong adapter name | [Check both](#netplan-apply-reports-an-error) |
| Machine takes ~2 minutes to boot | An adapter is configured but unplugged | [Mark it optional](https://ai-ops.com/docs/installation/network-configuration.md#if-the-machine-takes-two-minutes-to-boot) |
| `docker run hello-world` refuses with a permissions error | Group change not applied to this session | Run `newgrp docker`, or log out and back in |
| Container starts, then exits | Startup failure inside Koios | [Read the logs](#the-container-starts-then-exits) |
| Web interface unreachable | Ports in use, firewall, or still starting | [Work through the checks](#the-web-interface-is-unreachable) |
| Image loads but will not run | Wrong processor architecture | [Check the architecture](#the-image-will-not-run) |
| Browser warns the certificate is not trusted | Built-in self-signed certificate | Expected. [Replace it](https://ai-ops.com/docs/system/certificates.md) when convenient |

---

## During the Ubuntu Install

### The virtual machine will not boot the installer

A Generation 2 Hyper-V machine will not boot Ubuntu with its default security settings. It powers on, shows nothing useful, and lands in a boot menu.

Shut it down and either disable Secure Boot or set the template to the Microsoft UEFI Certificate Authority option. [Turn Off Secure Boot](https://ai-ops.com/docs/installation/hyper-v.md#step-4-turn-off-secure-boot) has the detail.

On a physical machine, the equivalent setting is in the firmware, and it may also need the boot mode set to UEFI rather than Legacy.

### There is no network address on the network screen

The machine is not reaching the network. On a virtual machine this is almost always the virtual switch: it must be **External** on Hyper-V, or bridged on other hypervisors. A NAT or internal switch produces exactly this.

On a physical machine, check the cable and that the switch port is live.

### The address set during install does not work

The installer asks for both a **Subnet** and an **Address**, and they are different things — the subnet is the whole network and ends in `0` (`192.168.1.0/24`), the address is this machine (`192.168.1.50`). Putting the machine's address in the Subnet field is accepted without complaint and leaves the machine unreachable.

Check what it actually ended up with, at the console:

```bash
ip -br addr && ip route
```

Correct it with [Changing the Address](https://ai-ops.com/docs/installation/network-configuration.md#changing-the-address).

### `ssh` is refused after the install

The OpenSSH server tick was missed on the installer's last screen. Install it at the console:

```bash
sudo apt update && sudo apt install -y openssh-server
```

---

## During Network Configuration

### `netplan apply` reports an error

Two causes account for nearly all of them.

**Indentation.** The file format treats leading spaces as meaning, two spaces per level, and rejects tab characters outright. If you pressed Tab while editing, replace those with spaces.

**The adapter name.** Confirm what the machine actually calls it:

```bash
ip -br link
```

The name in your configuration file has to match one of those exactly, ignoring `lo` and anything beginning `docker` or `veth`.

To see the file as netplan reads it:

```bash
sudo netplan get
```

### The address applied but nothing can reach the machine

Check the machine has both an address and a route:

```bash
ip -br addr && ip route
```

There must be a line beginning `default via`. Without it the machine can talk to its own network segment and nothing else — usually a missing or wrong `routes` section.

If names do not resolve but addresses work, the `nameservers` entry is wrong:

```bash
ping -c 3 1.1.1.1
ping -c 3 ubuntu.com
```

---

## During the Docker Install

### `hello-world` fails with a permissions error

The message mentions permission denied on the Docker socket. Your user was added to the `docker` group, but the current session started before that.

```bash
newgrp docker
```

Or log out and back in.

### `apt-get` cannot find the Docker packages

The repository was not added correctly. Re-run the two commands in [Add Docker's software repository](https://ai-ops.com/docs/installation/installing-docker.md#2-add-dockers-software-repository), then `sudo apt-get update` again and read its output — it names the repository if it cannot reach it.

On a machine behind a proxy, `apt` needs the proxy configured separately from anything else on the machine.

---

## Starting Koios

### The container starts, then exits

Something inside Koios failed during startup. The logs name the step:

```bash
sudo docker logs docker.koios.service
```

The most common causes:

| In the log | Meaning |
|------------|---------|
| A database migration failure | See [Server Won't Start](https://ai-ops.com/docs/troubleshoot/server-startup.md) |
| A schema version message | The image is older than the data on this machine. Use the version you were running, or newer |
| Out of disk space | Free space, then start it again |

Check disk space directly — it is the cause that gets overlooked:

```bash
df -h /var/lib/docker
```

### The image will not run

If the image loaded from an archive but will not start, and the error mentions the platform or architecture, it is the wrong build for this machine.

```bash
uname -m
```

`x86_64` needs the `amd64` archive; `aarch64` needs `arm64`. Download the matching one — the mismatch cannot be corrected on the machine.

### The web interface is unreachable

Work through these in order.

**Is it running?**

```bash
sudo systemctl status docker.koios.service
```

**Has it finished starting?** First start prepares the databases and takes several minutes. Watch it:

```bash
sudo docker logs -f docker.koios.service
```

**Is something else holding the ports?**

```bash
sudo ss -lntp | grep -E ':(80|443)\s'
```

You want to see Koios there and nothing else. Another web server on the machine will take the port first and Koios will fail to bind it. Either remove it or move Koios to other ports with [Environment Variables](https://ai-ops.com/docs/installation/environment-variables.md).

**Is the firewall blocking it?**

```bash
sudo ufw status
```

If active, ports 80 and 443 have to be allowed. See [Opening the Firewall](https://ai-ops.com/docs/installation/network-configuration.md#opening-the-firewall).

**Are you using the right address?** Confirm what the machine believes its address is:

```bash
ip -br addr
```

And browse to `https://` that address — not `http://`, which redirects, and not the name of the machine unless your DNS knows about it.

### The browser warns the certificate is not trusted

Expected on a new installation. Koios generates its own certificate on first start, and no browser trusts a self-signed certificate.

Continue past the warning to log in. To remove the warning properly, install a certificate signed by an authority your browsers trust, from **System > Certificates**. See [Certificates](https://ai-ops.com/docs/system/certificates.md).

---

## Collecting Information for Support

If you need to escalate, collect these first. They answer the questions that would otherwise be asked.

```bash
. /etc/os-release && echo "$VERSION_ID $(uname -m)"
```

```bash
sudo journalctl -u docker.koios.service --no-pager -n 200
```

```bash
sudo docker logs --tail 200 docker.koios.service
```

There is also a diagnostics bundle you can download from within Koios once it is running — see [Collecting Diagnostics](https://ai-ops.com/docs/troubleshoot/collecting-diagnostics.md).

## What's Next

- [Server Won't Start](https://ai-ops.com/docs/troubleshoot/server-startup.md): for a Koios that installed successfully and later stopped
- [Troubleshooting Overview](https://ai-ops.com/docs/troubleshoot/introduction.md): the full troubleshooting section