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 covers that instead.
Quick Reference
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 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:
Correct it with 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:
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:
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:
The address applied but nothing can reach the machine
Check the machine has both an address and a 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:
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.
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, 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:
The most common causes:
Check disk space directly — it is the cause that gets overlooked:
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.
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?
Has it finished starting? First start prepares the databases and takes several minutes. Watch it:
Is something else holding the ports?
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.
Is the firewall blocking it?
If active, ports 80 and 443 have to be allowed. See Opening the Firewall.
Are you using the right address? Confirm what the machine believes its address is:
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.
Collecting Information for Support
If you need to escalate, collect these first. They answer the questions that would otherwise be asked.
There is also a diagnostics bundle you can download from within Koios once it is running — see Collecting Diagnostics.
What's Next
- Server Won't Start: for a Koios that installed successfully and later stopped
- Troubleshooting Overview: the full troubleshooting section