Skip to main content

Troubleshooting & FAQ Hub

This central troubleshooting hub addresses the most common hardware and software questions encountered when building, configuring, and operating DeskPi cases, rackmount accessories, and cluster boards.

⚡ Quick Driver & Setup Cheatsheet​

For experienced builders who need instant access to one-line setup scripts:

1. DeskPi Pro Driver Suite (Raspberry Pi 4)​

Unified installer for DeskPi Pro PWM fan daemon and power button logic:

git clone https://github.com/DeskPi-Team/deskpi.git && cd deskpi/installation && sudo ./install.sh

To reconfigure fan speed temperature triggers at any time:

sudo deskpi-config

2. Enable PCIe NVMe on Raspberry Pi 5 (DeskPi Lite Pi 5 / DP-0039 / DP-0046)​

Append the external PCIe bus overlay to your boot configuration:

echo "dtparam=pciex1" | sudo tee -a /boot/firmware/config.txt && sudo reboot

❄️ Cooling & Fan Control Issues​

Q1: My cooling fan is not working, not spinning, or stopped completely.​

Common Causes & Diagnoses:

  1. Firmware Auto-Stop Feature (DeskPi Lite Pi 5 / Armor Lite V5): The PWM cooling fan on Raspberry Pi 5 cases is dynamically controlled by the official Raspberry Pi kernel PWM thermal table. By default, the fan stops spinning completely when CPU temperature is below 60°C to operate silently at idle.

    • Check your current CPU temperature: 
      vcgencmd measure_temp
    • If the temperature is under 60°C, fan inactivity is completely normal.
    • To test fan spin under load, run a brief CPU stress test: 
      sudo apt install -y stress
      stress --cpu 4 --timeout 30s
    • Ensure the RP1 fan overlay is enabled in /boot/firmware/config.txt: 
      dtparam=fan=on

  2. Unstarted Background Fan Daemon (DeskPi Pro & DeskPi Lite Pi 4):

    • On DeskPi Pro, verify the official fan service status: 
      sudo systemctl status deskpi.service
      sudo systemctl restart deskpi.service
    • On DeskPi Lite (Pi 4), if using the official deskpi_v1 driver, check deskpilite.service: 
      sudo systemctl status deskpilite.service
      sudo systemctl restart deskpilite.service

  3. Loose Fan Wiring / Header Pin Alignment: Inspect the fan cable connector. Ensure the JST-SH connector is fully inserted into the socket with correct pin alignment.

  4. Manual Full-Speed Test: Test whether the fan hardware spins by manually selecting speed level 4 (100%):

    sudo deskpi-config

Q2: My cooling fan runs at 100% full speed and will not throttle down.​

Cause: The PWM driver service is either not installed, not active, or blocked by the operating system kernel.

Solution:

  1. On DeskPi Pro, check the status of the background fan daemon: 
    sudo systemctl status deskpi.service
    Expected terminal output if running properly: 
    ● deskpi.service - DeskPi PWM Fan Daemon
         Loaded: loaded (/etc/systemd/system/deskpi.service; enabled; preset: enabled)
         Active: active (running) since Mon 2026-09-07 10:00:00 UTC; 5min ago
       Main PID: 1234 (pwmFanControl64)
          Tasks: 1 (limit: 4500)
         Memory: 2.1M
  2. If inactive or failed, restart the service: 
    sudo systemctl restart deskpi.service
  3. Verify that the 5V power cutoff helper service is also enabled: 
    systemctl is-enabled deskpi-cut-off-power.service
  4. On DeskPi Lite (Pi 4), verify deskpilite.service or check sudo raspi-config GPIO 14 fan settings.
  5. On Raspberry Pi 5 cases (Armor Lite V5), verify fan parameters in /boot/firmware/config.txt: 
    dtparam=fan=on

💾 M.2 Storage & Boot Issues​

Q2: My M.2 SSD is not detected in DeskPi Pro (DP-0001).​

Check SSD Protocol

DeskPi Pro supports M.2 SATA SSDs ONLY (B+M Key). It does NOT support M.2 NVMe SSDs (M-Key). If you install an NVMe SSD into DeskPi Pro, the internal USB-to-SATA bridge chip cannot communicate with the drive, and /dev/sda will not appear in lsblk.

How to verify your drive:

  • Inspect the drive connector notch: M.2 SATA drives have two notches (B-key and M-key). M.2 NVMe drives typically have only one notch (M-key).
  • Ensure the external USB 3.0 bridge adapter (rear U-shaped connector) is firmly plugged into both the Raspberry Pi 4 USB 3.0 port and the DeskPi Pro daughter board.

Q3: My NVMe SSD is not detected on Raspberry Pi 5 (DeskPi Lite Pi5 / DP-0039 / DP-0046).​

Solution:

  1. Raspberry Pi OS does not enable the external PCIe FPC connector by default. You must enable it manually in /boot/firmware/config.txt: 
    [all]
    dtparam=pciex1
  2. Save the file and reboot with sudo reboot.
  3. Verify the drive is enumerated on the PCIe bus: 
    lspci
    lsblk
    Expected output after successful enumeration: 
    # lspci shows the PCIe bridge and NVMe storage controller:
    0000:00:00.0 PCI bridge: Broadcom Inc. and subsidiaries BCM2712 PCIe Bridge (rev 21)
    0000:01:00.0 Non-Volatile memory controller: Silicon Motion, Inc. Device 2263 (rev 03)

    # lsblk shows the nvme0n1 block device:
    NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
    nvme0n1     259:0    0 476.9G  0 disk 
    ├─nvme0n1p1 259:1    0   512M  0 part /boot/firmware
    └─nvme0n1p2 259:2    0 476.4G  0 part /
  4. If the drive is still not listed, power down and check the 16-pin FPC ribbon cable orientation:
Gotcha: 16-Pin FPC Ribbon Cable Orientation
  • On the Raspberry Pi 5 motherboard, the FPC cable metallic contact pins must face inward towards the Ethernet/USB ports (the colored stiffener tab faces outward).
  • On the DeskPi expansion board, ensure contact pins align directly with the gold connector pads before pressing the locking collar closed.
  • If inserted upside down or tilted, the PCIe bus cannot detect the drive and will not initialize the NVMe controller.

Q4: Enabling PCIe Gen 3 causes system instability or filesystem errors.​

Cause: PCIe Gen 3 (~10 Gbps) operates beyond the official Raspberry Pi 5 specification (Gen 2.0 @ 5 Gbps). Signal integrity can vary depending on FPC cable seating and drive controller sensitivity.

Solution: If you experience PCIe bus resets (dmesg | grep -i pci reporting AER errors or link downgrades), comment out the Gen 3 parameter in /boot/firmware/config.txt:

[all]
dtparam=pciex1
# dtparam=pciex1_gen=3  <-- Comment this out to revert to stable Gen 2.0

Q5: How do I configure direct NVMe boot without a MicroSD card?​

  1. Update the Raspberry Pi bootloader EEPROM configuration: 
    sudo rpi-eeprom-config --edit
  2. Change the BOOT_ORDER entry to prioritize NVMe: 
    BOOT_ORDER=0xf416
    (Code 6 specifies NVMe boot; 1 specifies SD card fallback.)
  3. Save changes (Ctrl+O, Enter, Ctrl+X) and reboot.
  4. Clone or flash Raspberry Pi OS onto the NVMe SSD using the Raspberry Pi Imager or the built-in SD Card Copier (piclone).
  5. Remove the MicroSD card and power on.

⚡ Power, Buttons & OS Compatibility​

Q6: sudo ./install.sh fails on Debian 12 Bookworm with error: externally-managed-environment.​

Cause: Debian 12 (Raspberry Pi OS Bookworm) enforces Python PEP 668, preventing direct pip install into the system environment to avoid breaking OS-managed Python libraries.

Solution:

  1. The modern DeskPi Pro driver repository (DeskPi-Team/deskpi) deploys a compiled C fan daemon (pwmFanControl64V2) that operates independently of Python pip. Always run the official unified installer from the installation/ directory: 
    cd deskpi/installation/
    sudo ./install.sh
  2. If compiling manually from source or debugging on Bookworm, use the Makefile located under installation/drivers/c/: 
    cd deskpi/installation/drivers/c/
    make
    sudo make install
    This compiles pwmFanControl_v2.c to /usr/bin/pwmFanControl64V2 and safeCutOffPower.c to /usr/bin/safeCutOffPower64.
  3. Enable and start the service: 
    sudo systemctl daemon-reload
    sudo systemctl enable --now deskpi.service

Q7: What is the correct power-off sequence on DeskPi Lite Pi5?​

Rule: Soft shutdown first, physical disconnect second.

  1. Press the front soft power button twice (or execute sudo poweroff in the terminal).
  2. Observe the green Raspberry Pi activity LED. Wait until it stops blinking and the board halts completely.
  3. Click the rear latching power switch to cut off mains power. (Cutting power with the rear switch while the OS is actively writing to disk can corrupt your filesystem!)

🌐 Cluster Hardware (Super6C & Super4C)​

Q8: What happens when I press the front Reset button on the ITX Case Kit?​

Important Cluster Warning

The front panel Reset button resets all 6 CM4 nodes at the same time. It is a hardware-level line reset. Any unwritten database transactions, in-memory states, or container workloads across all six nodes will lose data. Reserve this button for catastrophic recovery when nodes are unresponsive.

Q9: How do I flash eMMC on a CM4 node on Super6C?​

To flash Raspberry Pi OS onto a Compute Module 4 with onboard eMMC:

  1. Locate the micro-USB slave port for the corresponding node on the Super6C board.
  2. Ensure the node's eMMC Boot Disable jumper (nRPIBOOT) is bridged.
  3. Connect the micro-USB cable to your host PC.
  4. Run rpiboot on your host PC to mount the CM4 eMMC storage as a mass storage device.
  5. Open Raspberry Pi Imager and flash the OS image.
  6. Once complete, remove the jumper and reboot the Super6C.

Need Further Assistance?​