# How to troubleshoot setup

Find why the installer stopped, and what to do about it.

For the full list of installer messages, see
[Messages](installer.md#messages).

## Prerequisites

- The terminal output of the failed run.

## Step 1: Find the message

The installer writes each refusal to stderr as one line,
`[i9] E<NAME>: <what happened> — <what to do>`, and exits with the status of
that name. The statuses are in [Exit status](installer.md#exit-status).

For a detached start that fails, the installer exits 7 (`ESERVER`) with
`the VM did not come up`. The reason is on stderr above that line — it may
be a startup-log path, a cap refusal, or another message from the binary.

A fetch that fails produces none of these lines. A wrong path in the
installer's URL gives `curl: (22) The requested URL returned error: 404`; a
wrong host gives `curl: (6) Could not resolve host: <host>`; another network
failure gives its own `curl: (N)` line. In each case `sh` runs an empty
script, and `curl -fsSL <url> | sh` exits 0 having installed nothing. If no
`[i9]` line appears, look for a `curl:` line, check that the URL is the one
the page names, and fetch first so a failed fetch fails the line:
`curl -fsSL <url> -o i9-install.sh && sh i9-install.sh` (see
[Exit status](installer.md#exit-status)).

## Step 2: Match the message

| stderr contains | Cause | Fix |
|-----------------|-------|-----|
| `[i9] EUSAGE:` | `I9_CHANNEL`, `I9_NO_BOOT` or `I9_DETACH` has a value the installer does not take | Set the value the line names, then run the installer again |
| `this host is` | The installer does not support this operating system or architecture | Use Linux x86_64 or arm64 with `/dev/kvm`, or macOS on Apple silicon |
| `has no build for` | The release has no binary for this host | Run the installer again later, or use a supported host |
| `the VM image is not published for` | The release data has no image for this architecture | Use a host with a published architecture. Don't substitute another architecture's image |
| `/dev/kvm is not readable` | This Linux host has no readable `/dev/kvm`, so it cannot run VMs | Enable KVM, or use a host that gives your user read access to `/dev/kvm`. `I9_NO_BOOT=1` installs the binary without a VM |
| `userfaultfd unavailable` | This user cannot open `userfaultfd`, which every VM boot needs; the kernel restricts it | Run `~/.i9/bin/i9 doctor`: its `userfaultfd` row names the setting that refuses it. Use a host where your user can open `userfaultfd`. `I9_NO_BOOT=1` installs the binary without a VM |
| `does not report that this host can run a guest` | `i9 doctor` found another reason this host cannot run a guest | Run `~/.i9/bin/i9 doctor` and read its `environment` rows |
| `neither sha256sum nor shasum is installed` | The installer has no tool to verify the binary | Install coreutils or perl, then run the installer again |
| `cannot create` or `cannot write in` | The installer cannot create `$I9_HOME` or `$I9_HOME/bin`, or write its staging file in `bin` | Set `I9_HOME` to a writable directory |
| `download of` | The binary download failed | Check the network, then run the installer again |
| `sha256 of the download is` | The downloaded binary does not match the signed release; nothing was installed | Report the line to security@i9.io |
| `is not verifiably signed` | The release's signature does not verify; nothing was downloaded | Report the line to security@i9.io |
| `was withdrawn` | The release was withdrawn; the line gives the reason | Run the installer again later |
| `is older than` | The release is older than a release already served | Run the installer again later |
| `could not be read just now` | The server could not read the release | Run the installer again in a minute |
| `channel has no VM image` | The `I9_CHANNEL` channel has a binary and no VM image | Run with `I9_NO_BOOT=1` to install the binary only, or use `stable` |
| `the VM did not come up` | `i9 run --detach` did not report the VM ready | The reason is on stderr above the line — read it and fix the cause |
| `the Windows hypervisor is not running` | Virtualization is off in the firmware, or Windows Hypervisor Platform is not turned on | Enable Intel VT-x or AMD-V in the BIOS or UEFI, turn on Windows Hypervisor Platform in Windows Features, and run the installer again |

`i9 run` prints `userfaultfd unavailable` for the same cause as the installer
row above.

## Step 3: Rule out messages that are not failures

| stderr contains | Meaning |
|-----------------|---------|
| `already installed` | The binary at `$I9_HOME/bin/i9` matches the signed release, so the installer skipped the download |
| `sha256 matches signed release` | The installer verified the binary and installed it |
| `add to PATH` | The binary is installed or already current; every run prints this line, with or without `I9_NO_BOOT=1`, and it shows the `PATH` export |
| `is live` | A detached run finished and a VM answers; the URL is the last stdout line. It is also printed when a VM of that name was already running and no second one was started |
| `host_kernel_no_uffd_wp` | The host can run and restore a guest and cannot capture one. Only `i9 vm save` refuses |

## Step 4: Check what the host can do

```sh
~/.i9/bin/i9 doctor
```

The `environment` section reports whether this machine can run, restore, and
capture a guest. A host that cannot capture shows these lines:

```text
    WARN  uffd write-protect         ABSENT
    This host can RUN and RESTORE a guest but cannot CAPTURE one
```

For a script, read the same verdict as JSON:

```sh
~/.i9/bin/i9 --json doctor
```

The `environment` object carries `can_run`, `can_restore`, and `can_capture`.

## Verify

Run the installer again. A detached start that works exits 0, prints the
session URL as its last line. `i9 run` writes the same URL to
`$I9_HOME/run/NAME.url`.

For the checks `i9 doctor` runs, see the
[CLI reference](cli.md#i9-doctor).
