Skip to content

Describe "No upgrade detected" situation in installer #415

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

Merged
merged 2 commits into from
Nov 21, 2025
Merged

Describe "No upgrade detected" situation in installer #415

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ece634a
troubleshooting/upgrade: leave some place for other cases
ydirson Nov 18, 2025
c2d18d2
troubleshooting/upgrade: describe first-boot service never completing
ydirson Nov 18, 2025
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
35 changes: 32 additions & 3 deletions docs/troubleshooting/installation-upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,11 @@ The target installation partition is mounted in `/tmp/root`.
## 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 cause 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.
:::

### UEFI/BIOS mismatch

For the installer to detect your current install (XCP-ng or XenServer), 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.

Expand All @@ -55,13 +57,40 @@ 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

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.

This can happen if the host was never fully booted after installation or upgrade, or if a specific first-boot service failed to execute properly.

To diagnose, check the installation log. See [During installation or upgrade](#during-installation-or-upgrade) to access the log file.

In this case, you would see one or two log lines like the ones below. If the system never booted, both messages typically appear:

```
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 you only see the "storage-init" line, error line, check the logs of `storage-init.service` in `/var/log/daemon.log` on the host (after rebooting into the original XCP-ng version you’re upgrading from).

If upgrading from an older release, you may instead get logs showing:

```
Upgradeability test failed:
Firstboot: ...
Missing state: ...
```

The "Missing state" line indicates which required first-boot service failed to complete.

## Installation logs

The installer writes in `/var/log/installer/`.
Expand All @@ -70,4 +99,4 @@ The main log file is `/var/log/installer/install-log`.

## Debugging the installer

You can [build your own installer](../../project/development-process/ISO-modification).
You can [build your own installer](../../project/development-process/ISO-modification).