The original troubleshooting guide is valuable because it starts below the CasaOS UI. When a drive, NIC, PCIe card, or USB device behaves strangely, the first question is whether the underlying Linux system can see the hardware at all.
The important 2026 boundary is operating system architecture. The 2023 guide assumes CasaOS running on a normal Debian/Ubuntu-style Linux installation. Current ZimaOS is a separate Buildroot-based appliance OS with a largely read-only system. Read-only diagnostic commands remain useful, but package installation and host modification instructions from ordinary Debian guides should not be copied into ZimaOS.
Use dmidecode for BIOS and Board Information
dmidecode reads SMBIOS/DMI data such as:
- BIOS vendor and version;
- release date;
- system/board identifiers;
- memory information;
- firmware capabilities such as UEFI.
This is useful when comparing a hardware-specific issue with a BIOS update or confirming exactly which board revision is running.
Use lspci to Confirm PCIe Hardware Is Enumerated
lspci lists devices the PCI subsystem sees: GPUs, SATA controllers, NVMe adapters, NICs, capture cards, and other expansion hardware.
If a new PCIe NIC never appears in lspci, the problem is below Docker/CasaOS. Check seating, power, firmware settings, lane sharing, and hardware compatibility before installing application software.
Use lsusb for USB Device Identity
lsusb reports USB vendor/product IDs. Those IDs are especially useful when diagnosing Wi-Fi adapters, Coral TPU devices, USB storage bridges, Zigbee coordinators, and other peripherals that may have several hardware revisions under one retail name.
Use dmesg for Driver and Boot-Time Hardware Messages
dmesg can show:
- kernel driver binding;
- firmware load failures;
- USB disconnect/reconnect events;
- storage I/O errors;
- NIC link changes;
- PCIe/AER errors.
Filter or capture only relevant sections rather than posting thousands of unrelated boot lines.
Use lsblk to Separate “Disk Not Detected” from “Disk Not Mounted”
lsblk shows disks, partitions, filesystem relationships, and mount points. A drive present in lsblk but absent from the CasaOS Files UI is a different failure from a drive missing from Linux entirely.
Prefer Read-Only Discovery Before Repair Commands
The original Part 1 is strongest when it teaches observation. Commands such as dmidecode, lspci, lsusb, dmesg, and lsblk can establish the problem layer without modifying storage or packages.
Do this before reformatting disks, reinstalling drivers, changing ownership recursively, or rebuilding Docker.
CasaOS and ZimaOS Need Different Host-Modification Rules
CasaOS normally runs on a general Linux host where apt may be available. ZimaOS is Buildroot-based and current IceWhale CLI guidance says most system folders remain read-only even as root.
Use the current ZimaOS CLI boundary when the same hardware runs ZimaOS.
Diagnose from Hardware Upward
A useful order is:
- BIOS/firmware detects hardware;
- Linux bus enumeration sees it;
- a kernel driver binds;
- the OS creates a usable interface/block device;
- CasaOS/ZimaOS exposes it in the UI;
- Docker/applications receive the device/path.
Skipping directly to layer six makes many hardware problems look like app bugs.
Use blkid to Identify Filesystem Type and UUID
The source Part 1 also uses blkid after lsblk. This answers a different question: what filesystem or LVM member signature does the partition actually contain, and which UUID/PARTUUID identifies it?
That is useful when a disk appears in Linux but a mount or storage manager does not recognize the expected filesystem. Record the output before reformatting anything.
Save the Hardware Evidence Before Changing Drivers or Storage
For a reproducible support report, capture the relevant command output together with:
- board model and BIOS version;
- operating-system version;
- device model plus PCI/USB ID;
- what changed immediately before the problem;
- whether the hardware appears in BIOS, Linux, and the CasaOS/ZimaOS UI.
This makes it possible to distinguish a missing driver from a failed cable, unsupported filesystem, or container mapping problem.
Linux Hardware Troubleshooting FAQ
What should I run first for an unknown PCIe card?
lspci is the quickest read-only check that the PCI subsystem sees it.
What is most useful for USB vendor/product IDs?
lsusb.
Can I use the guide's Debian package assumptions on ZimaOS?
No. Keep the diagnostic concepts, but follow ZimaOS-specific extension and driver rules.
