Skip to content

troubleshooting/upgrade: describe "previous installation not detected" cases #418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

troubleshooting/upgrade: describe "previous installation not detected" cases #418

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 27 additions & 5 deletions docs/troubleshooting/installation-upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Collaborator

@thomas-dkmt thomas-dkmt Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we're moving to a new section immediately after, we can replace "below" with an actual link to the relevant section/subsection.

Copy link
Contributor Author

@ydirson ydirson Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's actually not a cross-section link but "in the following subsections", and I felt it's lighter to the reader than "in the following subsections".


#### 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.
Expand All @@ -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.

Expand All @@ -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 may fail to detect an existing installation, and only offer to do a fresh install. 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 healthy 8.3 install) will give an idea whether something is wrong 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 of the cases where the log will exhibit "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/`.
Expand Down