ZimaOS Installation Troubleshooting Guide | ZimaSpace

Most ZimaOS installation failures can be traced to one of four areas: an incorrectly written installer drive, incompatible BIOS settings, unsupported storage or network hardware, or an incorrect boot sequence. Checking these areas in order is usually faster than repeatedly reinstalling the operating system.

This troubleshooting guide walks through the installation process from preparation to first access. It applies to supported Zima hardware and general x86-64 computers, although third-party hardware may require additional compatibility checks.

What to Check Before Installing ZimaOS

Before changing BIOS settings or rewriting the installer, confirm that the target computer meets the basic installation requirements.

The computer must use a supported 64-bit x86 processor.
The motherboard must support UEFI booting.
Secure Boot should be disabled before installation.
The storage controller should normally be configured to use AHCI mode.
The installer should be written to a reliable USB drive with sufficient capacity.
The destination disk must not contain data that you still need.

Important: Installing ZimaOS can overwrite the selected destination disk. Back up important files and verify the disk model and capacity before confirming the installation.

You can review the current operating system information on the official ZimaOS page. Users who prefer hardware developed for the Zima ecosystem can also explore the current ZimaCube 2 personal cloud NAS.

Download and Verify the ZimaOS Installer

Download the latest appropriate installer image from the official ZimaOS releases page. Avoid downloading installer images from unofficial mirrors because an outdated or modified image can introduce additional installation problems.

If a checksum is supplied with the release, compare it with the checksum of the downloaded file. A mismatch means the image may be incomplete or corrupted and should be downloaded again.

Common Download Problems

The archive cannot be opened: Download the image again and confirm that the download completed successfully.
The filename or extension looks incorrect: Make sure you downloaded an installer image rather than source code or a checksum file.
The installation stops at different points: Recheck the downloaded image before troubleshooting the destination hardware.

Create the Bootable USB Drive Correctly

The original community guide recommends using balenaEtcher to write the ZimaOS image to a USB drive. It performs a direct image write and includes a verification stage after flashing.

Install and open balenaEtcher.
Select the downloaded ZimaOS installer image.
Insert a USB drive with at least 8 GB of capacity.
Confirm that the selected target is the USB drive and not another storage device.
Start the flash process and wait for both writing and verification to finish.
Safely eject the USB drive before removing it.

Do not place the image file on the USB drive as a normal file. The image must be written to the entire drive with an imaging tool.

If Writing the USB Drive Fails

Try another USB port, preferably a port directly connected to the motherboard.
Temporarily close utilities that may be accessing or scanning removable drives.
Check whether the USB drive is write-protected.
Replace the USB drive if verification repeatedly fails.
Run the imaging tool with the permissions required by your operating system.

If You Used Ventoy or Rufus

If the USB drive was prepared with Ventoy or Rufus and the installer does not boot correctly, rewrite it with balenaEtcher before investigating other causes. A tool may create a bootable drive successfully for one operating system while handling a raw installer image differently for another.

Configure BIOS and UEFI Settings

Restart the computer and enter its firmware settings. Depending on the manufacturer, the required key is commonly F2, F12, Delete, or Esc. Consult the motherboard or computer documentation when the startup screen does not identify the correct key.

Check the following settings:

Boot mode: Select UEFI rather than Legacy or CSM mode.
Secure Boot: Disable it before booting the installer.
SATA or storage mode: Use AHCI where the hardware provides this option.
USB boot: Make sure booting from removable media is enabled.
Boot priority: Move the installer USB drive above the internal disk, or select it from the temporary boot menu.
Virtualization: Enable the relevant virtualization and VT-d options if you plan to use ZVM functionality.

If a Required BIOS Option Is Unavailable

Some manufacturers hide advanced options or require an administrator password before Secure Boot settings can be changed. A firmware update or restoration of default firmware settings may also expose options that are unavailable in the current configuration.

Record the existing settings before changing them. Changing storage mode on a computer that already runs another operating system may prevent that system from starting.

If the installer USB drive is missing from the boot menu, work through these checks:

Confirm that the image-writing process completed without a verification error.
Connect the drive before powering on or restarting the computer.
Try another motherboard USB port.
Disable Legacy or CSM boot mode and enable UEFI booting.
Temporarily disable Fast Boot if the firmware provides that setting.
Rewrite the image or test another USB drive.

If the USB drive appears on another computer but not on the target system, the problem is more likely related to the target computer’s firmware configuration than to the installer image.

Fix an Installation That Stops or Fails

When the installer starts but cannot complete, record the exact message displayed on the screen. A photograph of the error is often more useful than a general description such as “installation failed.”

The Destination Disk Is Missing

Confirm that the disk is detected in BIOS or UEFI.
Check power and data connections for SATA drives.
Switch the storage controller from RAID or Intel RST mode to AHCI when appropriate.
Review compatibility for unusual RAID controllers, storage adapters, or NVMe configurations.
Test the disk for hardware errors on another computer if possible.

The Installer Freezes or Restarts

Rewrite the installer image and test another USB drive.
Disconnect unnecessary USB devices and expansion cards.
Restore conservative BIOS settings instead of using CPU or memory overclocking.
Check system memory and storage health.
Record the last visible message before the system freezes.

Installation Fails on Third-Party Hardware

ZimaOS support for general x86-64 computers does not guarantee that every motherboard, storage controller, graphics adapter, or network interface will work. Some Intel NUC models and Intel-based Mac mini systems have been reported as problematic in community installation discussions.

Compatibility can also change as ZimaOS adds kernel, firmware, and driver updates. When reporting a failure, include the exact computer or motherboard model rather than only the product family.

Fix ZimaOS Not Booting After Installation

After installation finishes, remove the installer USB drive and restart the device. The internal destination disk should now be selected as the first UEFI boot device.

If the system returns to the installer, the USB drive is probably still connected or has higher boot priority. If the system displays a blank screen or blinking cursor, check the following:

The installation completed before the device was restarted.
The internal disk is visible in BIOS or UEFI.
The internal disk’s UEFI boot entry is selected.
Legacy or CSM mode has not been re-enabled.
Secure Boot remains disabled.
No other disk is taking priority over the ZimaOS system disk.

Reinstalling immediately may reproduce the same result. Check the boot mode and disk selection first.

Fix “Searching for Network Address”

A community reply reported an installation stopping at “Searching for network address” on an Intel NUC using a Realtek RTL8125BG-CG 2.5GbE controller. This message usually means that ZimaOS has not obtained a usable network address, but it does not by itself prove that the network adapter is unsupported.

Check the network in this order:

Connect the device directly to a router or switch with a known working Ethernet cable.
Confirm that the Ethernet port shows link or activity lights.
Try another cable and another router or switch port.
Open the router interface and check whether the device received a DHCP address.
Restart the router and ZimaOS device after reconnecting the cable.
Disable unused network adapters temporarily if the computer contains several interfaces.
Test a supported USB Ethernet adapter if the onboard controller is not detected.

If the router detects no connection and the Ethernet port has no activity lights, collect the exact network-controller model when requesting support. The controller name is more useful than describing it only as “2.5GbE.”

Fix a ZimaOS Dashboard That Cannot Be Opened

After ZimaOS starts, use another device connected to the same local network to open the assigned address in a browser. The address can usually be found in the router’s connected-device or DHCP-client list.

If the dashboard does not open:

Confirm that both devices are connected to the same local network.
Check whether the ZimaOS device received an IP address.
Try opening the numeric IP address directly.
Disable VPN or proxy software temporarily on the browser device.
Check whether guest Wi-Fi or client isolation prevents devices from communicating.
Restart the ZimaOS device and verify that the IP address has not changed.

An inaccessible dashboard does not always mean that installation failed. If the device appears in the router’s client list, the next step is to diagnose local network access.

About the Advanced Linux Installation Method

The community guide describes an alternative method that boots a Linux live environment and writes the ZimaOS image directly to the destination disk with the dd command. This method should be treated as an advanced recovery option.

Warning: A wrongly selected output disk in dd can immediately overwrite another drive. Do not use this method unless you can positively identify every connected disk and understand the command being executed.

Disconnecting unrelated storage devices before performing a direct disk write reduces the chance of selecting the wrong destination.

Information to Collect Before Asking for Help

If the problem remains unresolved, collect the following information before posting a support request:

Computer, mini PC, or motherboard manufacturer and exact model.
CPU model and installed memory.
Storage device model and connection type.
Network-controller model.
ZimaOS installer version and filename.
Tool used to create the installer USB drive.
Current UEFI, Secure Boot, and storage-mode settings.
The exact error message or a clear photograph of the screen.
The stage at which the problem occurs.
Troubleshooting steps already attempted.

This information helps separate an installer-media problem from a firmware, storage, bootloader, or network compatibility issue. Users can also visit the IceWhale Discord community when additional troubleshooting is required.

ZimaOS Installation FAQ

Does ZimaOS support Legacy BIOS?

ZimaOS installation requires UEFI-capable hardware. Disable Legacy or CSM mode when it conflicts with UEFI booting, and make sure the installer USB drive is selected from the UEFI boot menu.

Should Secure Boot be disabled?

Yes. Secure Boot can prevent the installer or installed system from starting correctly. Disable it in the motherboard firmware before beginning installation.

Can I create the ZimaOS installer with Rufus or Ventoy?

The community guide recommends balenaEtcher. If an installer created with Rufus or Ventoy does not boot or behaves unexpectedly, rewrite the image with balenaEtcher before continuing troubleshooting.

Why does ZimaOS not detect my storage disk?

The disk may be hidden behind an unsupported RAID or Intel RST configuration, disconnected, failing, or attached through an incompatible storage controller. Confirm that the disk appears in BIOS and use AHCI mode where appropriate.

Why is ZimaOS stuck on “Searching for network address”?

The device may not be receiving an address from the router, the Ethernet connection may be inactive, or the network controller may require different driver support. Test the cable, switch port, DHCP assignment, and exact adapter model.

Can ZimaOS be installed on an Intel NUC?

Some models may work, but compatibility varies by generation and by the storage and network controllers installed in the device. Verify the exact model and controller hardware instead of assuming that all Intel NUC systems behave identically.

Does installing ZimaOS erase the destination disk?

The installation process can overwrite the selected destination disk. Back up important files and verify the target disk before confirming installation.

How do I find ZimaOS after installation?

Check the router’s connected-device or DHCP-client list for the address assigned to the ZimaOS device. Open that address from a browser on the same local network.