troubleshooting/upgrade: previous installation not detected

Signed-off-by: Yann Dirson <[email protected]>

Author: ydirson

docs/troubleshooting/installation-upgrade.md

@@ -60,12 +60,16 @@ The ssh server will be available once the network is up. If you are unsure which
 ## The ISO installer does not offer to upgrade the existing install (XCP-ng or XenServer)
 
 :::note
-This section details how to deal with the most frequent causes for the installer not detecting your current installation. There can be other, rarer cases which are not detailed here.
+This section details how to deal with the most frequent causes for the installer not detecting your current installation. There can be other, rarer cases which are not detailed here.  In all cases the detailed reason for an inability to upgrade will always be possible to find in the installer log file.See [During installation or upgrade](#during-installation-or-upgrade) to access the log file.
 :::
 
-### UEFI/BIOS mismatch
+### Previous installation detected but not upgradable
 
-For the installer to detect your current install (XCP-ng or XenServer), the ISO must be booted in the same firmware context.
+In some cases the installer will detect a current install (XCP-ng or XenServer), but report "Only product installations that cannot be upgraded have been detected". The most common causes are listed below.
+
+#### UEFI/BIOS mismatch
+
+For the installer to detect your current install, the ISO must be booted in the same firmware context.
 The difference is how you pick the drive at boot. This applies to physical and virtual CD/DVD/USB drives.
 
 If your existing installation is in legacy BIOS mode, boot the ISO in BIOS mode.
@@ -85,14 +89,14 @@ Virtual CDROM Device         <<<<<< This one is the same device, in legacy BIOS
 ---------------------------------
 ```
 
-#### How to check if a running install is using UEFI or legacy BIOS?
+##### How to check if a running install is using UEFI or legacy BIOS?
 
 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 won't complete
+#### First-boot service won't complete
 
 During the first boot, several tasks finalize the installation. Each task logs a "done" stamp upon completion, and if any critical task fails, the system will block future upgrades.
 
@@ -119,6 +123,24 @@ Upgradeability test failed:
 
 The "Missing state" line indicates which required first-boot service failed to complete.
 
+### Previous installation not detected
+
+In other cases the installer will fail to detect a current install and only propose fresh installations. Some causes are listed below.
+
+#### Disk partitionning not recognized
+
+XCP-ng is quite strict about the partition table layout, partition labels, partition types.  If anything has modified it, it can prevent proper identification of the previous install.
+
+Log lines like the one below (taken from an upgrade of a sane 8.3 install) will give an idea whether something is wrng in this area.
+
+```
+Probe of /dev/nvme0n1 found boot=(True, '/dev/nvme0n1p4') root=(1, '/dev/nvme0n1p1') disk.state=(True, '/dev/nvme0n1p1') storage=(2, '/dev/nvme0n1p3') logs=(True, '/dev/nvme0n1p5')
+```
+
+#### Inconsistent inventory file
+
+The `/etc/xensource-inventory` file is critical to the upgrade process. This is one case where a log entry reading "A problem occurred whilst scanning for existing installations:" followed by more details.
+
 ## Installation logs
 
 On the installed system, installer logs are kept in `/var/log/installer/`.