troubleshooting/upgrade: describe first-boot service never completing

Signed-off-by: Yann Dirson <yann.dirson@vates.tech>

Author: ydirson

docs/troubleshooting/installation-upgrade.md

@@ -64,6 +64,33 @@ On the host, run `efibootmgr`.
 - If you see `EFI variables are not supported on this system.` you're running on legacy BIOS.
 - If you see some EFI boot entries, you’re running on UEFI.
 
+### First-boot service never completed
+
+A few tasks are normally done during first boot, as part of finalizing the installation.  Each of them leaves a "done" stamp when they finish, and as a sanity check the installer requires a few of them to have indeed succeeded, or will not consider the installation as upgradable.
+
+One possibility is that the host was never fully booted after it was last installed or upgraded, but there can be conditions preventing one single first-boot service to complete.
+
+Diagnosing this currently requires looking into the installation log. See [above](#during-installation-or-upgrade) to access the log file.
+
+In this case you would see one either or two log lines like the following.  If the system never booted, typically both lines are present:
+
+```
+Cannot upgrade nvme0n1, expected file missing: var/lib/misc/ran-storage-init (installation never booted?)
+Cannot upgrade nvme0n1, expected file missing: var/lib/misc/ran-network-init (installation never booted?)
+```
+
+If only the "storage-init" line is present, get more information from `storage-init.service` from the host (after rebooting into the original XCP-ng you want to upgrade).
+
+If upgrading from an older release, you may instead get logs showing:
+
+```
+Upgradeability test failed:
+  Firstboot:     ...
+  Missing state: ...
+```
+
+The "Missing state" line will similarly tell which required first-boot service never completed.
+
 ## Installation logs
 
 The installer writes in `/var/log/installer/`.