This document tells you how to troubleshoot Migrate to Virtual Machines
[OS adaptation](https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/resources/vm-adaptations)
errors and warnings.

Errors are critical issues that prevent execution of the OS adaptation. They
indicate underlying problems that require your immediate attention and
resolution before you can proceed with the process. Warnings, while not fatal,
provide valuable information for your awareness. They highlight potential issues
or inconsistencies detected during the adaptation process, even if cloning is
successful.

Each adaptation process generates an [adaptation report](https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/migrate/migration-progress-details#adaptation_report) which details any errors or
warnings encountered during the process.

While most OS adaptations are automated, in some cases you must troubleshoot and
fix errors and warnings to complete the cloning process. The following errors
and warnings highlight situations where such modifications are necessary.

## OS adaptation errors

The following table lists the errors that you might encounter during the OS
adaptation process, and the troubleshooting information for each error.

> [!NOTE]
> **Note:** Any value mentioned in curly braces {} is a placeholder that will be replaced with relevant value in real-time.

| Message | Action Item |
|---|---|
| Cannot find operating system on the VM disks. | Verify that the VM disks contain a valid operating system and that they are not encrypted, for example, with BitLocker. Changes to the source VM take effect in subsequent replication cycles. |
| No root file system with the provided UUID was found. | Verify there is a root file system with the provided UUID. |
| More than one file system was found with the provided UUID. File systems found: {roots} | Mark the operating system that you want to adapt. To mark the operating system, on Windows run `mkdir %SystemDrive%\Google\Migrate`, on Linux run `mkdir -p /etc/google/migrate && ls -la /dev/disk/*/* > /etc/google/migrate/disk-mappings-hints`. Changes to the source VM take effect in subsequent replication cycles. |
| More than one operating system was found on the VM disks. Root file systems found: {roots} | Mark the operating system that you want to adapt. In the Advanced section of the OS adaptation configuration, fill in the UUID of your root file system in the **Root file system uuid** field. Changes to the source VM take effect in subsequent replication cycles. |
| More than one root file system is marked with a hint directory. | Make sure that a hint directory exists only on a single root file system. On Windows: `%SystemDrive%\Google\Migrate`, on Linux: `/etc/google/migrate`. Changes to the source VM take effect in subsequent replication cycles. |
| Insufficient inodes on the {mount_point} file system. | Verify that at least {required_free_inodes} inodes are available on the {mount_point} file system. Changes to the source VM take effect in subsequent replication cycles. |
| Insufficient disk space on the {mount_point} volume. | Verify that at least {required_free_space_mb} MBs of free space is available on the {mount_point} volume. We recommend that you take a source snapshot before making changes to the {mount_point} volume. Changes to the source VM take effect in subsequent replication cycles. |
| VirtIO drivers are missing in the Linux kernel. | Verify that a Linux kernel with VirtIO driver support (`virtio_scsi`, `virtio_net`) is installed on the source VM. These drivers are required to run a migrated VM on Compute Engine. Changes to the source VM take effect in subsequent replication cycles. |
| The `/etc/fstab` file contains volatile critical entries, for example, non-persistent block device names. | Run `mkdir -p /etc/google/migrate && ls -la /dev/disk/*/* > /etc/google/migrate/disk-mappings-hints` on the source VM. Changes to the source VM take effect in subsequent replication cycles. |
| The {file_path} file contains volatile critical entries, for example, non-persistent block device names. | Run `mkdir -p /etc/google/migrate && ls -la /dev/disk/*/* > /etc/google/migrate/disk-mappings-hints` on the source VM. Changes to the source VM take effect in subsequent replication cycles. |
| Couldn't find {directory} or {directory} is empty. | Verify that {directory} exists, is not empty, and is not a soft link to a missing volume. Changes to the source VM take effect in subsequent replication cycles. |
| Couldn't find {file}. | Verify that {file} exists and it is not a soft link to a missing volume. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to mount critical entries from `/etc/fstab`, for example, duplicate `fstab` entries or missing devices. Error: {error_details} | Inspect the `/etc/fstab` settings in the source VM, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unsupported operating system: {os_description}. | See the product documentation for the list of supported operating systems - [Supported operating systems](https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/discover/supported-os-versions). |
| Unsupported operating system: amazonlinux2.0. | You have attempted to migrate a VM running an Amazon Linux 2 OS, which is not supported on Google Cloud. To migrate the VM, the OS must be converted to a supported OS. The capability of converting the OS to a supported OS is available as part of an experimental program - [Migrate an Amazon Linux 2 VM to Google Cloud](https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/migrate/migrate-aws-linux2). To perform a conversion, in the Advanced section of the OS adaptation configuration, select **Elevate Amazon Linux 2** . Alternatively, you can explore the experimental AI-powered process to rebuild your workload on a supported OS. To opt in to this experimental feature, contact us at [migrate-execution-ai-rebuild@google.com.](mailto:migrate-execution-ai-rebuild@google.com.) Changes to the source VM take effect in subsequent replication cycles. |
| BIOS to UEFI conversion is not supported on {os_description}. | See the product documentation for the list of supported operating systems for BIOS to UEFI conversion - [Supported operating systems](https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/discover/supported-os-versions). |
| Architecture {architecture} is not supported for {os_type} operating systems. | See the product documentation for the list of supported architectures - [Supported operating systems](https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/discover/supported-os-versions). |
| BIOS to UEFI conversion is not supported on {os_type} operating systems with architecture {architecture}. | See the product documentation for the list of supported architectures for BIOS to UEFI conversion - [Supported operating systems](https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/discover/supported-os-versions). |
| Couldn't detect a supported Linux bootloader, for example, Grub. This may occur in older operating systems or if the selected boot type (BIOS/UEFI) is not supported by the installed operating system. | See the product documentation for the list of supported operating systems, and verify that the boot type (BIOS/UEFI) of the operating system is set correctly - [Supported operating systems](https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/discover/supported-os-versions). |
| Cannot install package(s) google-compute-engine: {error_message} | Try resolving the underlying issues and installing the package manually, or contact support. If you want to continue without installing these packages, in the Advanced section of the OS adaptation configuration select **Skip failed install**. Note that skipping the installation may result in failures in later steps. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) {package_name}: {error_message} | Try resolving the underlying issues or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) {package_name}: {error_message} | Try resolving the underlying issues and installing the package manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) {package_name}: {error_message} | Try resolving the underlying issues and installing the package manually, or contact support. If you want to continue without installing these packages, in the Advanced section of the OS adaptation configuration select **Skip failed install**. Note that skipping the installation may result in failures in later steps. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install or update critical package(s) {packages} without breaking dependencies: {error_message} | Try manually installing package(s) {packages} on the source VM, or contact support. To skip the installation, in the Advanced section of the OS adaptation configuration, select **Skip failed install**. Note that skipping the installation may result in failures in later steps. Changes to the source VM take effect in subsequent replication cycles. |
| `DISM` installation of {driver} failed with the exit code: {exit_code} | Contact support or see Microsoft documentation - [Debug system error codes](https://docs.microsoft.com/en-us/windows/win32/debug/system-error-codes), to fix the error. Changes to the source VM take effect in subsequent replication cycles. |
| `DISM` installation of {driver} failed with the exit code: 2 | Disable any antivirus or other security software which may prevent `DISM` from accessing the file system. If the issue persists, run the commands: `sfc /scannow` and `dism /online /cleanup-image /restorehealth` to fix the issue. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to load the Windows registry of this VM. The {hive_name} hive might have inconsistencies. | Retry a replication cycle, test clone, cut over. If the issue persists, try fixing the registry using `Scanregw.exe`, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Timed out loading the Windows registry hives. | See Microsoft KB #2498915 to compress potentially bloated registry hives, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to decode `/etc/google/migrate/disk-mappings-hints` with utf-8 codec. | Rerun `mkdir -p /etc/google/migrate && ls -la /dev/disk/*/* > /etc/google/migrate/disk-mappings-hints` and verify if the written output is a valid utf-8. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to mount the file system on {mountable}. This usually indicates file system inconsistencies. | Try fixing the file system using tools such as {tool_name}. If the issue persists, contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to parse `/etc/fstab` due to the trailing commas at line {line_number}: {line_content} | Remove the trailing commas, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to parse `/etc/fstab` due to white-spaces in the path at line {line_number}: {line_content} | Replace the white-spaces with `\040` and validate by running `mount -a`, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to parse `/etc/fstab` as a quote is not terminated or closed at line {line_number}: {line_content} | Remove the non-terminated quote or close the quote and validate by running `mount -a`, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to parse `/etc/fstab` at line {line_number}: {line_content} | Run `mount -a` and fix the resulting errors, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to parse {path} at line {line_number}: {line_content} | Try fixing the format, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to find any kernel package installed even though `/boot` contains valid Linux kernel executable(s). | Reinstall the kernel using a standard package manager. If the issue persists, contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to find any kernel under `/boot`. | Verify that `/boot` contains a valid Linux kernel executable (`vmlinuz` or `Image`), or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Unable to find any `initrd` or `initramfs` images under `/boot`. | Verify that `/boot` contains a valid initial RAM disk image (`initrd` or `initramfs`), or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| The `/etc/fstab` file contains critical entries with missing volumes: {specs}. | Verify that the specified volumes exist, update the `/etc/fstab` file, try to fix the logical-volumes configuration, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to flush {volumes_or_disks}. Some volumes are marked by Windows as Dirty. | Run `chkdsk /f` on all available drives on the source VM. If the issue persists, contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Couldn't find `grub-mkconfig` and `grub2-mkconfig`. | Install the `grub2-common` package. Changes to the source VM take effect in subsequent replication cycles. |
| Couldn't update the bootloader using `grub-mkconfig` or `grub2-mkconfig`: {error_message} | Resolve the underlying issues or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| The partition table for the {devices} is invalid. | Fix the partition table with a tool such as FixParts. If the issue persists, contact support. Changes to the source VM take effect in subsequent replication cycles. |
| The sector size for the {devices} which is 4KB is not supported. | Ensure the device uses 512-byte sectors or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Failed adapting OS when `force_skip_verifications` flag is set. | Remove the `force_skip_verifications` flag by running the following command on the source VM. On Windows: run `rmdir %SystemDrive%\Google\Migrate\force_skip_verifications`, on Linux: run `rmdir /etc/google/migrate/force_skip_verifications`. |
| `tboot` is not supported. | Remove `tboot` from the bootloader configuration. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to update `/etc/sudoers`. This is required to allow the guest environment to add `sudo` permissions to users based on IAM roles. | Verify `/etc/sudoers` is editable on the source VM, or run `touch /etc/google/migrate/skip_editing_sudoers` to skip editing `/etc/sudoers`. Note that granting `sudo` access through IAM roles won't work on a VM without these changes. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to update `/etc/sudoers`: permission denied. This is required to allow the guest environment to add `sudo` permissions to users based on IAM roles. | Verify `/etc/sudoers` is editable on the source VM, or run `touch /etc/google/migrate/skip_editing_sudoers` to skip editing `/etc/sudoers`. Note that granting `sudo` access through IAM roles won't work on a VM without these changes. Changes to the source VM take effect in subsequent replication cycles. |
| This image has already been generalized (`sysprep.exe /generalize` has already been executed). | Retry without the `generalize` option selected. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to generalize the image by executing `sysprep.exe /generalize`. | Generalize the source image and retry without the `generalize` option selected. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to install packages due to `dpkg` misconfigured package(s): {packages} | Rebuild `dpkg` configuration by running `rm /var/cache/debconf/config.dat && dpkg --configure -a`. If this fails or the error persists, remove the failing package(s), rebuild the `dpkg` configuration again, and then re-install the package(s) if needed. Changes to the source VM take effect in subsequent replication cycles. |
| Timed-out configuring `dpkg`. | Rebuild `dpkg` configuration by running `rm /var/cache/debconf/config.dat && dpkg --configure -a`. If this fails or the error persists, remove the failing package(s), rebuild the `dpkg` configuration again, and then re-install the package(s) if needed. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to boot the adapted VM to complete the conversion. | Boot failures occur due to inconsistent snapshots. Try powering off the source VM, replicating a powered off clone of the source VM, or using disk migration instead. Changes to the source VM take effect in subsequent replication cycles. |
| The operating system cannot be automatically converted to Rocky Linux 8. | We recommend that you use the VM disk migration flow to migrate your VM to Google Cloud. See [Migrate VM disks](https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/migrate/migrating-disks). |
| The instance does not have an active boot partition or an EFI partition. | Please verify that your instance includes its boot partition or its EFI partition, or contact support. |
| The `skip package installation` option cannot be used with the `{hint}` hint directory, which was found on the VM at `{hint_path}`. | The `{hint}` hint requires installing packages. Either clear the `skip package installation` option in the OS adaptation configuration, or remove the hint by running `rmdir {hint_path}` on the source VM. Changes to the source VM take effect in subsequent replication cycles. |

## OS adaptation warnings

The following table lists the warnings that you might encounter during the OS
adaptation process, and the troubleshooting information for each warning.

> [!NOTE]
> **Note:** Any value mentioned in curly braces {} is a placeholder that will be replaced with relevant value in real-time.

| Message | Action Item |
|---|---|
| The following package(s) were broken and had to be removed in order to install critical packages: {packages} | Remove the broken packages and verify that your VM and applications are working as expected. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot apply {requested_license} license to {os_info}. | Choose an applicable license from: {applicable_licenses}. |
| The `/etc/fstab` file contains volatile entries, for example, non-persistent block device names. | Run `mkdir -p /etc/google/migrate && ls -la /dev/disk/*/* > /etc/google/migrate/disk-mappings-hints` on the source VM. Changes to the source VM take effect in subsequent replication cycles. |
| The `/etc/fstab` file contains {mount_type} entries. | Verify that all the {mount_type} entries are accessible from the target VM after migration, or that the target VM successfully boots without access to the {mount_type} entries. Changes to the source VM take effect in subsequent replication cycles. |
| The {file_path} file contains volatile critical entries, for example, non-persistent block device names. | Run `mkdir -p /etc/google/migrate && ls -la /dev/disk/*/* > /etc/google/migrate/disk-mappings-hints` on the source VM. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) google-compute-engine: {error_message} | Resolve the underlying issues and install the package(s) manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) google-osconfig-agent: {error_message} | Resolve the underlying issues and install the package(s) manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) google-cloud-sdk: {error_message} | Resolve the underlying issues and install the package(s) manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) google-cloud-cli: {error_message} | Resolve the underlying issues and install the package(s) manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) google-rhui-client: {error_message} | Resolve the underlying issues and install the package(s) manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) cloud-regionsrv-client: {error_message} | Resolve the underlying issues and install the package(s) manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) google-cloud-sap-agent: {error_message} | Resolve the underlying issues and install the package(s) manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) dhcp-client: {error_message} | Resolve the underlying issues and install the package(s) manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Cannot install package(s) {package_name}: {error_message} | Resolve the underlying issues and install the package(s) manually, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Missing VMware Tools. The VM may not be able to shut down gracefully. A forced shut down may result in data loss. | Install VMware Tools or gracefully shutdown your VM before executing a cut-over. Changes to the source VM take effect in subsequent replication cycles. |
| The security software: {software} can potentially lead to first boot configuration failures and connectivity issues. | Create a test clone and verify that the new VM instance boots successfully with network connectivity. Otherwise, consider disabling {software}, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to add metadata server to {hosts_path}. | Verify that {hosts_path} exists and is editable by the user: Administrator. Changes to the source VM take effect in subsequent replication cycles. |
| Failed to set NTP special poll interval registry value. | Verify that the registry path {path} is editable by the user: Administrator. Wait for the changes to get applied, or manually edit the registry to set its value to {value}. Changes to the source VM take effect in subsequent replication cycles. |
| The network outbound of one of the following profile types: {profiles} is blocked, and not merged with local firewall policy. This can potentially lead to first boot configuration failures and connectivity issues. | Consider allowing the merge of local firewall policies by setting `AllowLocalPolicyMerge` to 1 in all the mentioned profiles. Alternatively, define a remote policy which allows RDP and metadata-server access, or contact support. Changes to the source VM take effect in subsequent replication cycles. |
| Package `cpio` was missing or misconfigured, and was installed to allow properly configuring the operating system. Package `pax` was installed to prevent vulnerability to CVE-2022-41352. | If needed, packages `cpio` and `pax` can be removed post migration. |
| Some packages don't have a proper replacement and were removed, downgraded or excluded from conversion. Check the file {removed_packages_file_path} for the list of the removed packages, the file {downgraded_packages_file_path} for the list of the downgraded packages and the file {excluded_packages_file_path} for the list of the excluded packages. | Install the removed, downgraded and excluded packages as needed on the target VM to restore application capabilities. |
| File system inconsistency or corruption was detected and repaired on the XFS file system: {filesystem} | You can repair the damaged file system at the source using tools such as `xfs_repair`. If you don't want to repair the damaged file system, use the `disable-xfs-repair` flag. However, doing this can potentially lead to OS adaptation failures and further issues. Changes to the source VM take effect in subsequent replication cycles. |
| OpenSSH was configured to use MACs or Ciphers algorithms which are removed from OpenSSH: {removed_algorithms}. To avoid connection issues post migration, these algorithms were removed from the SSH daemon config file. | You can manually configure the SSH daemon config file, if needed, at the source or after the migration. Changes to the source VM take effect in subsequent replication cycles. |
| Security rules that block the `VFAT` file system were detected. This policy conflicts with the requested BIOS to UEFI conversion, as the `VFAT` file system is required for UEFI boot. To prevent boot failures, the security rules were disabled in these kernel modules config files: {config_files}. | You can manually configure the kernel modules config files, if needed, at the source or after the migration. Note that re-enabling these security rules will prevent the system from properly booting in UEFI mode. Changes to the source VM take effect in subsequent replication cycles. |