Introduction
This article lists common problems you might encounter while getting an EVE-OS (Edge Virtualization Engine) image, flashing it, installing it on an edge device, and bringing the device online for the first time. It gives the cause and the fix for each. It is a companion to Get EVE-OS, Flash an EVE-OS installer or live image, and Install EVE-OS on an Edge Device.
Problems are grouped by the stage where they appear:
- Building the EVE-OS image.
- Flashing and booting the installer.
- During installation.
- First boot and connecting to Edge Infrastructure Services.
Building the EVE-OS Image
Windows: the image is 0 bytes, won't boot, or is corrupt
Cause: In PowerShell, the > redirect writes text (UTF-16) and mangles the binary image stream, producing an unusable file.
Fix: Do not redirect with > on Windows. Mount an output directory with -v <dir>:/out and let the container write the file there. For example:
docker run -v $HOME/eve-overrides:/in -v $HOME/eve-images:/out lfedge/eve:- installer_raw
/in injects your custom config (such as the server file); /out captures the output artifact. They are independent mounts (include both when you need a custom cluster and an output file).
The image ignores your cluster and connects to zedcloud.zededa.net
Cause: Your server file was not injected into the image. This happens when the -v $HOME/eve-overrides:/in mount is missing from the build command, or when the server file itself is malformed.
Fix:
- Include -v $HOME/eve-overrides:/in in the docker run command (installer and live images only; rootfs images do not take a server file).
- Make sure the server file is a single line containing only your cluster hostname (optionally hostname:port), with no byte-order mark (BOM) and no extra lines. On Windows, create it with ASCII encoding:
Set-Content -Path "$HOME\eve-overrides\server" -Value "zedcloud.example.zededa.net" -Encoding ASCII
"Cannot connect to the Docker daemon"
Cause: Docker is not running, or your user lacks permission.
Fix: Start Docker Desktop (macOS/Windows). On Linux, add your user to the docker group or run with sudo.
Wrong or missing image tag (manifest unknown, pull fails)
Cause: The version/architecture tag you requested does not exist on Docker Hub.
Fix: Confirm the tag on Docker Hub under the Tags tab before building. Two common mistakes:
- Architecture mismatch. Use -arm64 for ARM hardware and -amd64 for x86.
- Patch level differs by architecture. The latest LTS is not always the same number across architectures.
Wrong installer format for your target
Cause: installer_raw and installer_iso are different artifacts.
Fix:
- Use installer_raw for a normal USB or disk-based install (the raw disk image you flash).
- Use installer_iso only when the target's BIOS/BMC cannot boot a disk-based image (for example HPE iLO or Dell DRAC virtual media).
- Use installer_net for PXE network boot.
"server file is locked or read-only"
Cause: The partition holding the file is mounted read-only.
Fix: Unmount the partition, then edit the file. See the post-install / unmounting instructions referenced in Get EVE-OS.
Flashing and Booting the Installer
The USB drive is not offered in the boot menu
Cause: A bad flash, the wrong firmware boot mode, or firmware security settings.
Fix:
- Re-flash the drive and try a different USB port.
- Ensure the device is set to boot the installer media (UEFI entry) first.
- If the media still won't boot under UEFI, check whether Secure Boot needs to be disabled for your firmware.
Wrong-architecture image won't boot
Cause: An amd64 image on ARM hardware, or an arm64 image on x86.
Fix: Rebuild with the tag that matches the device architecture.
During Installation
The device keeps re-entering the installer (reinstall loop)
Cause: The installer USB is still attached and boot order still prefers it, so the device reboots back into the installer.
Fix: After installation completes and the device powers down, remove the installer USB, then set the boot order to the internal disk that now contains EVE-OS.
Applications or VMs fail to start after install
Cause: Hardware virtualization is disabled in firmware.
Fix: In the BIOS/UEFI, enable Intel VT-x (Virtualization Technology) and VT-d. EVE-OS runs workloads as VMs and needs these.
Installation does not complete on specific hardware
Cause: Some hardware models and firmware combinations are not yet qualified for EVE-OS, or need model-specific configuration. Installation can stall, fail to finish, or complete but never connect. Examples seen in support include certain Lenovo and HPE nodes and hardware that is not on the approved device list.
Fix:
- Confirm the target hardware is on the ZEDEDA approved device list before deployment.
- If the model is not listed, contact support. There is a file on the USB install drive that contains information support can use to help configure the model in Edge Infrastructure Services.
- Record the exact hardware model, firmware version, and EVE-OS version when you open a case, because the fix is often specific to that combination.
First Boot and Connecting to Edge Infrastructure Services
The device returns a 404 or "not found" during onboarding
Cause: The server value points the edge device at the UI and API hostname instead of the device onboarding hostname. Each cluster exposes two hostnames. The zedcontrol.<cluster>.zededa.net hostname serves the web UI and zcli. Edge devices onboard against the zedcloud.<cluster>.zededa.net hostname. A device pointed at the zedcontrol hostname reports a 404 or a "not found" error and never onboards.
Fix:
- Set the server value (in the server file baked into the image, or in the single-use installer configuration) to the zedcloud onboarding hostname for your cluster, for example zedcloud.int.example.zededa.net.
- Do not use the zedcontrol hostname as the device server value.
- If you are unsure which onboarding hostname applies to your cluster, confirm it with your ZEDEDA account team.
"No IP address" / the device never reaches Edge Infrastructure Services
Cause: A fresh, generic installer relies on last-resort networking, which assumes DHCP on a wired Ethernet port, no enterprise proxy, and no WiFi/cellular. If none of those holds, the device cannot reach Edge Infrastructure Services. See Enable Last Resort.
Fix:
- Provide DHCP on a wired Ethernet port and allow outbound access on port 443.
- If the site requires a static IP or a proxy, do not use the generic installer. Use a single-use EVE-OS installer that carries the bootstrap configuration prepared for the device.
The device reaches Edge Infrastructure Services on the wrong interface, then goes offline
Cause: The edge node model or configuration assigns the management role to a network interface that has no IP address. The device first reaches Edge Infrastructure Services using last resort networking on a different interface that does have an IP, but the configured management interface fails, so the device does not stay online. The web UI can show the device booting and report a last-seen time while it never becomes stable.
Fix:
- Verify that the management interface in the edge node model matches the physical port that has connectivity.
- Reassign the management role to the interface that obtains an IP address by DHCP.
- On multi-port hardware, confirm which physical port carries management traffic before you onboard the device.
The device reaches port 443 but never onboards (TLS inspection)
Cause: A network security product (for example Zscaler or another SSL/TLS inspection proxy) intercepts the outbound HTTPS session, re-signs it with its own certificate, and breaks the certificate chain that attestation depends on. The edge device reaches port 443, but attestation cannot complete, so Edge Infrastructure Services cannot verify the device identity. Symptoms include the device appearing to connect while onboarding stalls, and messages such as Not yet published AttestEscrow.
Fix:
- Add an SSL inspection bypass (not a simple allow rule) for the onboarding hostname so the TLS session passes through untouched. An allow rule still lets the proxy decrypt and re-encrypt the traffic, which does not fix the problem.
- Confirm the bypass works by checking the de
Vault won't unseal after a reboot / secrets and apps become inaccessible
Cause: EVE-OS seals its encrypted vault to TPM PCR-1, which measures the firmware's list of boot options. Attaching a bootable USB device changes that list, changes PCR-1, and prevents the vault from unsealing on the next boot.
Fix:
- Remove the installer USB after installation.
- If you attach a USB device for extra storage, make sure it has no bootable partition. To check (replace /dev/sda with your device):
parted /dev/sda print | grep boot
No output means the device has no bootable partition and is safe to leave attached.
"Connected but not onboarded"
Cause: This is expected. The device has reached Edge Infrastructure Services but no matching edge node object has been onboarded yet.
Fix: In Edge Infrastructure Services, create the edge node object and onboard it using the device's soft serial number (found in the INVENTORY partition directory created during install). See Onboard Edge Nodes.
WiFi-only device
Cause: Onboarding a device that has only WiFi connectivity needs extra setup (WiFi credentials cannot be assumed by last-resort networking).
Fix: Contact support for assistance with an initial WiFi connection.
Attestation and PCR Template Mismatches
EVE-OS uses measured boot and remote attestation to confirm that an edge node is running trusted firmware and software before Edge Infrastructure Services trusts it. The device reports a set of Platform Configuration Register (PCR) values from its Trusted Platform Module (TPM). Edge Infrastructure Services compares those values against a PCR template. When the reported values do not match the template, attestation fails and the edge node cannot come fully online. See Manage PCR Templates for template information.
Device attestation failed: PCR index N value mismatch
Cause: The reported PCR value for one or more indexes no longer matches the assigned PCR template. The likely trigger depends on the index.
- PCR index 2 usually reflects PCIe option ROM firmware. It changes after a NIC, GPU, or other PCIe firmware update, a hardware change on a PCIe slot, a BIOS/UEFI version upgrade, a BIOS setting change that alters option ROM loading, a boot device path change, or an interrupted firmware flash.
- PCR index 13 usually reflects the root filesystem or system files. It changes after a rootfs modification.
- A failing storage device can also cause a mismatch. If the console shows an error such as error: failure reading sector ... from 'hd0' during boot measurement, the disk is likely failing.
Fix:
- Identify what changed on the device on or before the date the mismatch first appeared.
- If the change was expected (for example a planned firmware or hardware update), update the PCR template with the new expected values taken from a known-good reference device.
- If the change was not expected, restore the device to its previous state.
- If a storage or hardware fault is indicated (for example a sector read error at boot), replace the device (RMA).
A hardware model can have more than one PCR template
This is expected. PCR values do not depend on the EVE-OS image version alone. They also reflect the device firmware (BIOS) version and boot configuration. Two devices of the same hardware model running the same EVE-OS version can report different PCR values if they use different BIOS versions or BIOS settings (for example boot order, USB boot, or fast boot). As a result, a single hardware model can legitimately have several PCR templates for the same EVE-OS version.
Prerequisites before an EVE-OS rollout with attestation enforced
Before you upgrade any edge node that has attestation enforced, confirm that a PCR template for the target EVE-OS image version and firmware combination already exists and is populated with expected values.
To prepare for the rollout:
- Obtain expected PCR values from a known-good reference device already running the target EVE-OS version and firmware.
- Add or update the matching PCR template before you start the rollout.
- Prefer a direct upgrade to the target version. Staging through an intermediate version and then rolling back can leave a distinct fingerprint (for example in PCR index 14) and cause the device to match a rollback-labeled template instead of the standard one.
A bootable USB device is a separate cause of PCR problems. It changes the firmware boot option list and PCR index 1, which prevents the vault from unsealing. That case is covered in the preceding "Vault won't unseal after a reboot" subsection.
Known issue: the vTPM endorsement key changes after an upgrade
Symptom: After an EVE-OS upgrade (for example from the 14.x series to the 16.x series) or a server firmware upgrade (for example an HPE SPP update), an edge application that relies on the virtual TPM (vTPM) misbehaves, and the vTPM endorsement key changes. Recovery has required purging and re-provisioning the affected application with the new key.
Status: This behavior is under active investigation with ZEDEDA engineering and does not have a documented permanent fix yet. If your applications depend on a stable vTPM endorsement key, contact support before you upgrade EVE-OS or server firmware on affected hardware.
Re-Onboarding and Stale Node Records
These problems occur when an edge node already existed in Edge Infrastructure Services and is being removed, replaced, or onboarded again.
An edge node is missing from the UI and ZCLI but still reachable by its UUID
Cause: A delete left a residual record in the backend. The primary device record is gone, so the edge node does not appear in the web UI or in ZCLI list and search results, but a direct URL or API lookup by UUID still returns a partial object. This is sometimes called an orphaned or stale node record.
Fix:
- Contact support to remove the residual record.
- After the record is fully removed, onboard the edge node again.
Re-onboarding leaves the edge node stuck in the provisioned state
Cause: The device identity in Edge Infrastructure Services conflicts with a previous record. This happens after a mainboard or system-board replacement changes the hardware UUID while the serial number stays the same, or when a duplicate record from an earlier onboarding still exists. The device reaches Edge Infrastructure Services, but Edge Infrastructure Services cannot resolve its identity, so the device stays in the provisioned state.
Fix:
- Remove every conflicting edge node record from Edge Infrastructure Services, including both the old and the new entries for the affected serial number.
- Reinstall EVE-OS on the device.
- Onboard the device again using its soft serial number.
How an edge node is identified after a reinstall or physical move
EVE-OS identifies an edge node by its soft serial number, recorded in the INVENTORY partition directory created during install, together with its hardware identity.
- A reinstall on the same hardware keeps the same identity.
- A physical move to a different site does not change the identity, but it can change networking (for example a different subnet or DHCP scope), so verify connectivity at the new location.
- If hardware changes as part of the move, follow the steps in the preceding "Re-onboarding leaves the edge node stuck in the provisioned state" subsection.
Reference: Which Mount Does What
| Docker argument | Purpose |
| -v <dir>:/in | Overwrites config-partition files (for example server) with your local copies. Required to target a non-default cluster on installer and live images. |
| -v <dir>:/out | Writes the output artifact into a folder instead of to stdout. Use this on Windows (PowerShell) to avoid corrupting the binary image. |
| > <file> | Redirects the output artifact to a file. Works on macOS/Linux; do not use in PowerShell. |
| --rm | Removes the pulled container after the command completes (optional). |