Troubleshooting DEEPX DX-M1 on Raspberry Pi 5: Error Messages and Fixes

This page lists the DEEPX DX-M1 error messages we see most often on Raspberry Pi 5, each with its cause, a command to confirm it, and the fix. Most trace back to four areas: the PCIe link, missing kernel headers for the DKMS driver build, version mismatches between dx_rt, the driver and the NPU firmware, and DX-COM compile settings. Entries cover the Sixfab AI HAT and the Sixfab Edge AI Expansion Board.

Search this page (Ctrl+F) for the line your terminal printed. Most headings are the error exactly as the tool prints it; a few describe a symptom instead.

Tested on: Raspberry Pi 5 (8 GB), Raspberry Pi OS Trixie 64-bit, dx_rt v3.4.2, dxrt-driver-dkms v2.6.0, DX-COM 2.4.1.
Last verified: 2026-10-21

Didn't find your error? Post it in the Sixfab Community with the full output and the result of the sanity check described below. See Still stuck? Ask the community for what to include.

Quick answers

Start here: two commands that narrow down most problems

Run these before anything else. Together they tell you whether the problem is hardware, driver or software.

lspci -d 1ff4:

1ff4 is DEEPX's PCI vendor ID. Expected: one line for the card, e.g. 0001:01:00.0 Processing accelerators: DEEPX Co., Ltd. DX_M1 (rev 01). No output means the card isn't on the PCIe bus (go to PCIe and hardware).

cd dx_rt_npu_linux_driver
sudo ./sanity_check.sh

Expected last line: ** Sanity check PASSED!. On failure it writes sanity/result/dxrt_issue_bundle_<timestamp>.tar.gz. Keep that file; you'll need it if you ask for help in the Sixfab Community or open a support ticket.

Version compatibility for dx_rt v3.4.2

Most runtime errors on this page are version mismatches. dx_rt v3.4.2 refuses to start below these minimums on Linux:

Source: device_version.h and model.h in dx_rt.

Board-specific driver floors from the driver release notes: Raspberry Pi 5 safe link-up needs driver v1.8.0 or later; Raspberry Pi 4 (BCM2711) needs v2.3.0 or later for the 64-bit PCIe TLP fix.

Contents

• Driver install: APT and DKMS
• dx_rt build
• PCIe and hardware
• Performance and thermals
• Runtime and version compatibility
• DX-COM model compilation
• FAQ
• Still stuck? Ask the community

Driver install: APT and DKMS

dpkg: dependency problems prevent configuration of dxrt-driver-dkms (dkms not installed)

DKMS is missing. The driver package builds its kernel modules with DKMS and declares Depends: dkms, build-essential. apt installs those for you; dpkg -i does not.

dpkg: dependency problems prevent configuration of dxrt-driver-dkms:
 dxrt-driver-dkms depends on dkms; however:
  Package dkms is not installed.

Check:

dpkg -l dkms

Expected: dpkg-query: no packages found matching dkms

Fix:

sudo apt update
sudo apt install dkms
sudo dpkg --configure -a

Verify:

dkms status -m dxrt-driver-dkms

Expected, for example: dxrt-driver-dkms/2.6.0-2, 6.18.50+rpt-rpi-2712, aarch64: installed

To avoid this next time, install a local package file with apt: sudo apt install ./dxrt-driver-dkms_2.6.0-2_all.deb.

Applies to: dxrt-driver-dkms v2.6.0.

E: Unable to locate package apt-repo-sixfab

You're following a deprecated install path. The apt-repo-sixfab package isn't available from your configured sources. The release file below works on Raspberry Pi OS Bookworm and Trixie. Install it from the release file, then continue with setup.

$ sudo apt install apt-repo-sixfab
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
E: Unable to locate package apt-repo-sixfab

Check:

grep VERSION_CODENAME /etc/os-release

Expected: VERSION_CODENAME=bookworm or VERSION_CODENAME=trixie. Both work with the fix below.

Fix:

wget https://github.com/sixfab/sixfab_dx/releases/download/v0.1/apt-repo-sixfab.deb
sudo apt install ./apt-repo-sixfab.deb
sudo apt update

Verify:

apt-cache policy apt-repo-sixfab

Expected: Installed: shows a version, not (none). Then continue with the AI HAT setup guide.

Applies to: Raspberry Pi OS Bookworm and Trixie.

ERROR: Manual installation detected in /lib/modules/

A manually built driver is blocking the DKMS package. A manual build (./build.sh -c install) puts modules under /lib/modules/<kernel>/extra/; the DKMS package uses /lib/modules/<kernel>/updates/dkms/. The package's install script stops when it finds the manual copies so two versions of dxrt_driver never load together.

Checking for conflicting manual installation...
ERROR: Found manually installed module: dxrt_driver.ko
/lib/modules/<kernel>/extra/rt/dxrt_driver.ko
ERROR: Found manually installed module: dx_dma.ko
/lib/modules/<kernel>/extra/pci_deepx/dx_dma.ko

===================================================================
ERROR: Manual installation detected in /lib/modules/
===================================================================

Check:

find /lib/modules/$(uname -r)/extra -name 'dx*.ko'

Expected: dxrt_driver.ko and/or dx_dma.ko listed.

Fix: Remove the manual install, then let the package finish configuring.

If you still have the source tree:

cd dx_rt_npu_linux_driver/modules
sudo ./build.sh -c uninstall

If you deleted it:

sudo rm /lib/modules/$(uname -r)/extra/rt/dxrt_driver.ko \
        /lib/modules/$(uname -r)/extra/pci_deepx/dx_dma.ko
sudo depmod -a

Then:

sudo dpkg --configure -a

Verify:

dkms status -m dxrt-driver-dkms
lsmod | grep -E 'dxrt_driver|dx_dma'

Expected: the module shows installed for your kernel, and both modules are listed.

Applies to: dxrt-driver-dkms v2.6.0.

ERROR: Kernel configuration is invalid. when building the driver

Kernel headers for your running kernel aren't installed, so the modules can't be built. The message has two spaces after the colon.

 ERROR:  Kernel configuration is invalid.
         missing  /lib/modules/<kernel>/build/include/generated/autoconf.h,
                  /lib/modules/<kernel>/build/include/config/auto.conf
 ** Please Install: sudo apt install --reinstall linux-headers-<kernel>

Check:

ls /lib/modules/$(uname -r)/build

Expected: No such file or directory, or an empty folder.

Fix:

Raspberry Pi 5:

sudo apt install linux-headers-rpi-2712

Raspberry Pi 4:

sudo apt install linux-headers-rpi-v8

Then rebuild:

./build.sh
sudo ./build.sh -c install --reload

Verify: sudo ./sanity_check.sh ends with ** Sanity check PASSED!

Applies to: driver v2.6.0.

[ERROR] /dev/dxrt0 has incorrect permissions (works only with sudo)

The udev rule that opens /dev/dxrt* to all users is missing. This usually follows a manual driver install. You'll notice it first as apps that find the device only under sudo.

==== Device File Check ====
[OK] /dev/dxrt0 exists.
[OK] /dev/dxrt0 is a character device.
[ERROR] /dev/dxrt0 has incorrect permissions: <600> (expected: 0666)

Check:

ls -l /dev/dxrt*
ls /etc/udev/rules.d/51-deepx-udev.rules

Expected: permissions are not crw-rw-rw-, and the rule file is missing.

Fix:

cd dx_rt_npu_linux_driver/modules
sudo ./install-udev_rule.sh

This writes /etc/udev/rules.d/51-deepx-udev.rules and reloads udev.

Verify: ls -l /dev/dxrt0 shows crw-rw-rw-. Run your app without sudo.

Applies to: driver v2.6.0.

WARNING: Old driver modules are still loaded in memory. after upgrading the driver

An app or the dxrt service held the device during the upgrade, so the old modules couldn't be unloaded. The new modules are installed on disk and load on the next boot.

Warning: dxrt_driver module is in use and could not be unloaded.

===================================================================
WARNING: Old driver modules are still loaded in memory.

New module files will be installed, but the old version remains
active until reboot. A reboot is REQUIRED to complete the upgrade.
===================================================================
...
Skipping module loading - old driver modules are still active.
The newly installed modules will be used after reboot.
Skipping service restart - reboot required to activate new modules.

Fix:

sudo reboot

Verify:

modinfo -F version dxrt_driver
cat /sys/module/dxrt_driver/version

Expected: both show the new version.

Before the next upgrade, stop your apps and run sudo systemctl stop dxrt.

Applies to: dxrt-driver-dkms v2.6.0.

dx_rt build

[WARNING] PEP 668 externally-managed-environment error detected!

dx_rt's build.sh needs a Python virtual environment on Bookworm and Trixie. It installs the dx-engine Python package with pip. Without a venv, pip targets the system Python, which both releases mark as externally managed (PEP 668). The C++ runtime still builds; only the Python package is skipped.

[WARNING] PEP 668 externally-managed-environment error detected!
[WARNING] Skipping Python package installation due to system restrictions.
[HINT] Please use --venv_path option or activate a virtual environment:
example)$ python3 -m venv ./venv-dxnn; ./build.sh --venv_path ./venv-dxnn

Check:

echo $VIRTUAL_ENV

Expected: empty.

Fix (either option):

Pass the venv to build.sh:

python3 -m venv --system-site-packages ./venv-dxnn
./build.sh --venv_path ./venv-dxnn

Or activate it first:

python3 -m venv --system-site-packages ./venv-dxnn
source ./venv-dxnn/bin/activate
./build.sh

--system-site-packages keeps system packages such as OpenCV visible inside the venv.

Verify:

source ./venv-dxnn/bin/activate
python3 -m pip list | grep dx-engine

Expected: one dx-engine line with a version number.

If CMake fails after this, see the next section.

Applies to: dx_rt v3.4.2, Raspberry Pi OS Bookworm and Trixie.

[ERROR] CMake configuration failed. If a Python virtualenv is active, it may be shadowing system cmake.

A cmake installed by pip inside your venv is running instead of the system CMake. Another Python package often pulls it in, and it tends to show up right after the PEP 668 fix above.

[ERROR] CMake configuration failed. If a Python virtualenv is active, it may be shadowing system cmake. Try deactivating the venv or ensure system CMake is used.

Check:

which cmake

Expected: a path inside the venv, e.g. <./venv-dxnn/bin/cmake>.

Fix:

source ./venv-dxnn/bin/activate
pip uninstall cmake
sudo apt install cmake
./build.sh --venv_path ./venv-dxnn

Verify: which cmake prints /usr/bin/cmake, and the build finishes.

If you see [ERROR] CMake binary not found. Please install cmake (e.g., sudo apt install cmake) and retry. instead, run sudo apt install cmake.

Applies to: dx_rt v3.4.2.

PCIe and hardware

These four form one diagnostic flow. If lspci -d 1ff4: prints nothing, use the first two entries and let the card LED decide between them. If lspci shows the card but the runtime doesn't, use the last two and check whether the kernel modules are loaded.

[ERROR] No supported DEEPX devices found (vendor=1ff4, device=0000 0100 0110 0101 0111).

The card didn't enumerate on the PCIe bus at boot. A soft reboot often doesn't reset the card. Do a full power-cycle first.

==== PCI Link-up Check ====
[ERROR] No supported DEEPX devices found (vendor=1ff4, device=0000 0100 0110 0101 0111).

Check: lspci -d 1ff4: prints nothing. Look at the card LED. If it's light blue or near white, skip to the next section.

Fix: Shut down with sudo shutdown -h now, unplug the power supply from the wall, wait about 10 seconds, and plug it back in. sudo reboot doesn't fully reset the card.

Verify:

lspci -d 1ff4:

Expected: one line for the card, listed as DEEPX Co., Ltd. DX_M1. Then sudo ./sanity_check.sh shows [OK] Supported DEEPX devices found. (num=1).

Applies to: hardware.

No supported DEEPX devices found with the card LED light blue or near white

The PCIe link isn't coming up. The FFC cable isn't fully seated, or the cable or connector is damaged. The sanity check prints the same line as the previous section; the LED colour is what tells them apart.

Fix:

1. Power off and unplug the supply.
2. Open both connector latches, reinsert the cable fully at both ends with the contacts facing the correct side, and close the latches.
3. Power on and run lspci -d 1ff4:.
4. Still missing? Swap in another PCIe FFC cable and check again.

Verify: lspci -d 1ff4: lists the card.

If the card is still missing with a known-good cable, the board's PCIe interface is suspect. Run sudo ./sanity_check.sh and open a support ticket with sanity/result/dxrt_issue_bundle_<timestamp>.tar.gz and a photo of the LED.

Applies to: hardware.

Device not found from dxrt-cli -s, but lspci lists the card

The card enumerates, but the runtime can't use the link at the Raspberry Pi 5's default PCIe speed. The card LED is fully off after boot in this state. Enable PCIe Gen 3.

$ dxrt-cli -s
Device not found

Check: Rule out a driver problem first:

sudo ./sanity_check.sh

Expected: [OK] dxrt_driver module is loaded. and [OK] dx_dma module is loaded. If either says NOT loaded, go to the next section instead.

Fix:

sudo nano /boot/firmware/config.txt

Add these lines at the end of the file:

dtparam=pciex1
dtparam=pciex1_gen=3

Save and exit (Ctrl+X, then Y, then Enter), then reboot:

sudo reboot

Verify:

dxrt-cli -s

Expected: the device and its versions, with the link at Gen 3:

DXRT v3.4.2
=======================================================
 * Device 0: M1M, Accelerator type
---------------------   Version   ---------------------
 * RT Driver version   : v2.6.0
 * PCIe Driver version : v2.5.0
-------------------------------------------------------
 * FW version          : v2.7.4
--------------------- Device Info ---------------------
 * Memory : LPDDR4 4200 Mbps, 1.92GiB
 * Board  : M.2, Rev 0.0
 * Chip Offset : 1
 * PCIe   : Gen3 X1 [01:00:00]

NPU 0: voltage 750 mV, clock 1000 MHz, temperature 41'C
NPU 1: voltage 750 mV, clock 1000 MHz, temperature 41'C
NPU 2: voltage 750 mV, clock 1000 MHz, temperature 41'C
=======================================================

Applies to: Raspberry Pi 5, dx_rt v3.4.2.

[ERROR] dxrt_driver module is NOT loaded. after a kernel update

DKMS couldn't rebuild the driver for your new kernel. DKMS rebuilds the DEEPX modules on every kernel update, but it needs the matching kernel headers. Without them, no module exists for the kernel you booted.

==== Kernel Module Check ====
[ERROR] dxrt_driver module is NOT loaded.
[ERROR] dx_dma module is NOT loaded.
[ERROR] PCIe <01:00.0> driver probe is fail.

Check:

uname -r
dkms status -m dxrt-driver-dkms
ls /lib/modules/$(uname -r)/updates/dkms/

Expected: no installed line for the running kernel, and no dxrt_driver.ko or dx_dma.ko in the folder.

Fix:

Raspberry Pi 5:

sudo apt install linux-headers-rpi-2712

Raspberry Pi 4:

sudo apt install linux-headers-rpi-v8

Then:

sudo dkms autoinstall
sudo modprobe dx_dma
sudo modprobe dxrt_driver

Verify: sudo ./sanity_check.sh ends with ** Sanity check PASSED!

Applies to: dxrt-driver-dkms, any version.

Performance and thermals

Low FPS on the DEEPX DX-M1 (PCIe link running at Gen 2)

The Raspberry Pi 5 runs its PCIe link at Gen 2 by default, which caps NPU throughput. Enable Gen 3.

Check:

sudo lspci -vv -d 1ff4: | grep LnkSta:

Expected at default: LnkSta: Speed 5GT/s, Width x1 (Gen 2).

Fix: Add to the end of /boot/firmware/config.txt:

dtparam=pciex1
dtparam=pciex1_gen=3

Then sudo reboot.

Verify: The same command shows LnkSta: Speed 8GT/s, Width x1 (Gen 3). lspci may append (downgraded) to the width. The speed is what matters. dxrt-cli -s also lists PCIe : Gen3 X1.

We recommend Gen 3 for every DEEPX DX-M1 setup on a Raspberry Pi 5.

If FPS starts high and drops after a few minutes under load, that's thermal throttling (next section).

Applies to: Raspberry Pi 5.

Throttling notice: Device-ID=0 NPU-ID=0 temperature is N°C.

The NPU is running hot and lowering its clock to protect itself. FPS drops after sustained load, unlike the Gen 2 case where it's low from the start. The severe form is Throttling emergency occurred: Device-ID=0 NPU-ID=0.

Throttling notice: Device-ID=0 NPU-ID=0 temperature is N°C.

You may not see this line in your terminal. On dx_rt v3.4.2 we watched the clock fall without it, so check the clock directly:

Check:

dxrt-cli -m 1

NPU 0: voltage 750 mV, clock 1000 MHz, temperature 64'C
...
NPU 0: voltage 750 mV, clock 800 MHz, temperature 88'C

Expected: the temperature climbs while your workload runs. When the clock drops below 1000 MHz, the NPU is throttling. In our test, three parallel yolo26-x processes took the NPU from 64 °C to 89 °C in about four minutes, and the clock fell from 1000 MHz to 800 MHz.

Fix: Fit a heatsink or fan to the card and improve airflow in the case. A passive cooler is the minimum. An active cooler (fan) is better if you have one.

Verify: Rerun the same workload for 10 minutes with dxrt-cli -m 1 open. Expected: the clock stays at 1000 MHz and FPS holds steady.

Applies to: dx_rt v3.4.2.

Runtime and version compatibility

Check the version table first. Upgrading the runtime, driver and firmware together avoids most of these.

The current device driver version is X.Y.Z. Please update your device driver to version 2.5.0 or higher.

The runtime is newer than the installed dxrt_driver kernel module. dx_rt v3.4.2 needs driver 2.5.0 or later on Linux.

The current device driver version is X.Y.Z.
Please update your device driver to version 2.5.0 or higher.

Check:

modinfo -F version dxrt_driver

Fix:

sudo apt update
sudo apt install --only-upgrade dxrt-driver-dkms
sudo reboot

Verify: modinfo -F version dxrt_driver prints 2.5.0 or later, and dxrt-cli -s runs without the error.

Applies to: dx_rt v3.4.2.

The current pcie driver version is X.Y.Z. Please update your pcie driver to version 2.4.0 or higher.

The dx_dma PCIe module is older than the runtime expects. dx_rt v3.4.2 needs 2.4.0 or later. dx_dma ships in the same package as dxrt_driver, so the fix is the same as the previous section.

The current pcie driver version is X.Y.Z.
Please update your pcie driver to version 2.4.0 or higher.

Check:

modinfo -F version dx_dma

Fix:

sudo apt update
sudo apt install --only-upgrade dxrt-driver-dkms
sudo reboot

Verify: modinfo -F version dx_dma prints 2.4.0 or later.

Applies to: dx_rt v3.4.2.

The current firmware version is X.Y.Z. Please update your firmware to version 2.7.0 or higher.

The NPU's on-board firmware is older than the runtime supports. dx_rt v3.4.2 needs firmware 2.7.0 or later.

The current firmware version is X.Y.Z.
Please update your firmware to version 2.7.0 or higher.

Check:

dxrt-cli -i

Fix: Download the firmware file from the open-source DEEPX firmware repository, where you can also inspect it before flashing, then:

dxrt-cli -u <firmware.bin>

The device resets after the update by default. Keep the power connected until the update finishes.

If the card reports The current device firmware is X.Y.Z. The firmware must be version 2.0.0 or higher to update., it can't update itself. Open a support ticket.

Verify: dxrt-cli -i shows firmware 2.7.0 or later.

Applies to: dx_rt v3.4.2.

The model's compiler version(X.Y.Z) is not compatible in this RT library.

The .dxnn was compiled with a DX-COM older than 1.18.1, which dx_rt v3.4.2 no longer loads.

[dxrt-exception] Invalid model exception {"The model's compiler version(1.17.0-rc1) is not compatible in this RT library.
Please use a model file generated with a compiler version 1.18.1 or higher.":...buildTasksAndSubgraphMap} error-code=262

Fix (either): Recompile the original ONNX with a current DX-COM, or download the model again from the Sixfab Model Zoo.

Verify: The new .dxnn loads and runs.

Applies to: dx_rt v3.4.2.

version 'VERS_1.20.1' not found (required by libdxrt.so)

The app loaded an ONNX Runtime older than 1.20.1. dx_rt links against libonnxruntime.so.1 and needs version 1.20.1 or later. If an older copy comes first in the library path, the app stops at load time, before dx_rt can print its own version message.

run_model: /path/to/libonnxruntime.so.1: version `VERS_1.20.1' not found (required by /usr/local/lib/libdxrt.so)

dx_rt may also print its own message when it checks the version: The current ONNX Runtime version is X.Y.Z. Please update your ONNX Runtime to version 1.20.1 or higher.

Check: See which libonnxruntime the app loads:

ldd $(which run_model) | grep -i onnx
echo $LD_LIBRARY_PATH

Expected: libonnxruntime.so.1 resolves to a path in /usr/local/lib/, for example /usr/local/lib/libonnxruntime.so.1. If it points to another folder, such as one listed in LD_LIBRARY_PATH, that copy is the old one.

Fix: Take the old copy's folder out of LD_LIBRARY_PATH (run unset LD_LIBRARY_PATH, and remove the line from ~/.bashrc if it sets it). If the old copy sits in a system folder, remove it or replace it with ONNX Runtime 1.20.1 or later.

The onnxruntime pip package is a separate copy. Upgrading it doesn't affect this error.

Verify: ldd shows ONNX Runtime 1.20.1 or later, and your app starts.

Applies to: dx_rt v3.4.2.

dxrt service is not running

The dxrt systemd service is stopped or was never enabled. The runtime talks to the dxrtd daemon, which runs as this service. This is common after a manual build.

$ run_model -m model.dxnn
...
Inference by loops: count=30
[dxrt-exception] Service input & output exception {dxrt service is not running} error-code=264

Check:

systemctl status dxrt

Expected: inactive (dead) or Unit dxrt.service could not be found.

Fix:

sudo systemctl enable --now dxrt

If the unit doesn't exist, rerun dx_rt ./build.sh on the device. It creates dxrt.service.

Verify: systemctl is-active dxrt prints active.

Applies to: dx_rt v3.4.2.

Dynamic IPC task init failed or Ran out of NPU memory

The models loaded on one card exceed its NPU memory. This usually comes from several large models, or from creating a new inference engine per thread or request. We hit it on a 2 GB card by starting 17 copies of a 113 MB model. On dx_rt v3.4.2 the failing app printed this:

[dxrt-exception] Service input & output exception {"Dynamic IPC task init failed":/__w/dx_rt/dx_rt/dx_rt/lib/device_pool/service_layer.cpp:353:SignalTaskInitLocked} error-code=264

Other dx_rt builds print Ran out of NPU memory, or Ran out of NPU memory for task id=N.

Check: Watch the NPU memory fill while your apps run. dxtop shows it per device, for example 1.72 GiB / 1.92 GiB. Then load your models one at a time and note which one triggers the error.

Fix: Load fewer or smaller models per card, and reuse one inference engine per model. The DEEPX DX-M1 comes in 1 GB and 2 GB NPU memory versions. Run dxrt-cli -s and read the Memory line to see which one you have. A 2 GB card reports 1.92GiB.

Verify: All models load and run.

Applies to: dx_rt v3.4.2.

DX-COM model compilation

All examples compile with:

dxcom -m model.onnx -c config.json -o out/

A successful compile writes out/<model>.dxnn. The configuration rules come from the dx-compiler JSON configuration reference.

Error in PhaseLabels.SURGERY: [UnknownError] with a YOLO model

DX-COM reports a PPU configuration it can't apply with this message, and the message doesn't say which part is wrong. A wrong layer node name, a wrong ppu.type and a ppu block on a model without a YOLO-style detection head all produce the same error. Check the three in order.

[ERROR] - Error in PhaseLabels.SURGERY: [UnknownError]
[ERROR] - Unknown error occurred during compilation. Please contact DEEPX.

1. Check the layer node names. Names under ppu.layer must exist in your ONNX graph. Example names from the DEEPX docs (Mul_441, Sigmoid_442) won't match your export, and newer exporters use path-style names. Open the model in Netron and trace back from the outputs:

• Type 0 (YOLOv3, YOLOv4, YOLOv5, YOLOv7): the detection-head Conv layers, e.g. /model.105/m.0/Conv.
• Type 1, YOLOv8 and later: back from the final Concat. bbox usually comes from a Mul or Add, cls_conf from a Sigmoid.

For a YOLOv8n exported with Ultralytics at 640 x 640, these names compiled with DX-COM 2.4.1. Yours may differ:

"ppu": {
  "type": 1,
  "conf_thres": 0.25,
  "num_classes": 80,
  "layer": [ {"bbox": "/model.22/Mul_2", "cls_conf": "/model.22/Sigmoid"} ]
}

2. Check that ppu.type matches the model family.

3. Check that the model needs a PPU at all. The PPU only accelerates YOLO-style detection heads. Classification models (ResNet, MobileNet) and segmentation models (DeepLab, U-Net) don't use it. Remove the whole ppu block from the config.

Also set num_classes to the model's actual class count. YOLOv8-style heads output [1, 4 + num_classes, N], so [1, 84, 8400] means 80 classes. The PPU has a class limit. For a model with a very large class count, remove the ppu block and run post-processing on the CPU.

Verify: The compile finishes and writes the .dxnn. A YOLOv8n with the config above compiled to a .dxnn file in our test.

Applies to: DX-COM 2.4.1.

Input name not found in model (inputs)

The key under inputs must exactly match the ONNX input tensor name. Exporters use different names (images, input, input.1), so names copied from examples often don't match.

[ERROR] - Error in PhaseLabels.PREPARE: ConfigInputError
[ERROR] - Input names mismatch between model and config.

Check:

python3 -c "import onnx; m=onnx.load('model.onnx'); print([i.name for i in m.graph.input])"

Expected: e.g. ['images']

Fix:

"inputs": { "images": [1, 3, 640, 640] }

Verify: The compile finishes.

Applies to: DX-COM 2.4.1.

ConfigInputError: Input shape mismatch (batch size is not 1)

DX-COM takes the input shape from your config and checks it against the model. The batch dimension must be 1 in both. A model with a symbolic batch dimension compiles as long as the config says 1. A config that says anything else fails.

[ERROR] - Error in PhaseLabels.PREPARE: ConfigInputError
[ERROR] - Input shape mismatch for input 'images' at dimension 0: model shape (1, 3, 64, 64), config shape [2, 3, 64, 64].

Check:

python3 -c "import onnx; m=onnx.load('model.onnx'); print(m.graph.input[0].type.tensor_type.shape)"

Compare the result with the inputs entry in your config. Expected: the first dim in the config is 1.

Fix: Set the batch dimension in the config to 1:

"inputs": { "images": [1, 3, 640, 640] }

A model exported with a fixed batch other than 1 also fails to compile. Re-export it with a static batch of 1. With Ultralytics:

from ultralytics import YOLO
YOLO("yolov8n.pt").export(format="onnx", dynamic=False, batch=1)

Export with dynamic=False. A YOLOv8n exported with dynamic=True (dynamic batch, height and width) failed with Error in PhaseLabels.SURGERY: [UnknownError] in our test, even with a fixed shape in the config.

Verify: The compile finishes and writes the .dxnn.

Applies to: DX-COM 2.4.1.

Multi-input model with a JSON config

dxcom with a JSON config supports a single input only. Multi-input models need the dx_com Python module with a torch DataLoader.

[ERROR] - Error in PhaseLabels.SURGERY: DataLoaderError
[ERROR] - The dataloader provides a single input, but the model expects 2 inputs.

Check: The input-name command from the "Input name not found in model" section prints more than one name.

Fix: Compile with the dx_com Python module and a torch DataLoader. batch_size must be 1, and for multi-input models each item should be a dict keyed by the ONNX input name. This example follows the DEEPX documentation ("Python Wheel Package Usage" in Execution of DX-COM):

import dx_com
from torch.utils.data import Dataset, DataLoader

class CustomDataset(Dataset):
    def __init__(self):
        # Initialize your dataset
        pass

    def __len__(self):
        return len(self.data)

    def __getitem__(self, idx):
        # Multi-input: return a dict keyed by ONNX input node name (recommended).
        return self.data[idx]

dataset = CustomDataset()
dataloader = DataLoader(dataset, batch_size=1, shuffle=True)

dx_com.compile(
    model="model.onnx",
    output_dir="./compiled",
    dataloader=dataloader,
)

Apply the same preprocessing inside __getitem__ that you use at inference time. The JSON preprocessings block isn't used when you pass a DataLoader.

Applies to: DX-COM 2.4.1.

No calibration images found (default_loader)

Either dataset_path is wrong, or your files' extensions aren't in file_extensions. Treat the match as case-sensitive: jpg doesn't cover JPG.

[ERROR] - Error in PhaseLabels.PREPARE: DataNotFoundError
[ERROR] - Given extensions ['jpg'] do not exist in /path/to/dataset.

Check:

find <dataset_path> -type f | sed 's/.*\.//' | sort | uniq -c

Expected: zero files, or extensions missing from your list (e.g. 100 JPG).

Fix:

"file_extensions": ["jpg", "JPG", "jpeg", "JPEG", "png"]

Verify: Calibration runs over calibration_num samples and the compile finishes.

Applies to: DX-COM 2.4.1.

Error in PhaseLabels.QUANTIZATION: [UnknownError] with enhanced_scheme and --use_q_pro

Automatic Q-PRO (--use_q_pro) and a manual enhanced_scheme can't be combined, and DX-COM doesn't say so in the message. Both pick a DXQ quantization scheme. Each option compiles on its own, and together they fail.

[ERROR] - Error in PhaseLabels.QUANTIZATION: [UnknownError]
[ERROR] - Unknown error occurred during compilation. Please contact DEEPX.

Check: Look for enhanced_scheme in your config and --use_q_pro in your command.

Fix: Keep --use_q_pro and delete enhanced_scheme from the config, or keep enhanced_scheme and drop the flag. enhanced_scheme needs DX-COM v2.1.0 or later.

Verify: The compile finishes.

Applies to: DX-COM 2.4.1.

Deprecation warning for ppu.type = 2

PPU type 2 is deprecated as of DX-Compiler v2.4.0 and will be removed in a future release. It still compiles and prints a warning.

[WARNING] - PPU type 2 post-processing is deprecated and will be removed in a future release. Use dx_com.pre_optimize(model, passes={'yolo_postprocess': {...}}) instead.

Fix: Move to the dx_com.pre_optimize() API. It does the same TopK-first optimization and adds instance segmentation and YOLO26 support. This example follows the "Migration from PPU Type 2" section of that page. Replace the layer names with your model's, and note that input_height and input_width are required:

import onnx
import dx_com

model = onnx.load("model.onnx")
optimized = dx_com.pre_optimize(model, passes={
    "yolo_postprocess": {
        "layers": [
            {"bbox": "bbox_head_p3", "cls_conf": "cls_head_p3"},
            {"bbox": "bbox_head_p4", "cls_conf": "cls_head_p4"},
            {"bbox": "bbox_head_p5", "cls_conf": "cls_head_p5"},
        ],
        "num_classes": 80,
        "topk": 512,
        "input_height": 640,
        "input_width": 640,
    },
})
dx_com.compile(model=optimized, config="config.json", output_dir="./output")

Verify: The new flow compiles without the warning.

Applies to: DX-Compiler v2.4.0 and later.

Low accuracy after compiling, and the log shows [INFO] - Added nodes:

The compiler folded your preprocessing into the NPU graph, and your host code applies it a second time.

[INFO] - Added nodes: Div(x=255)

Check:

grep "Added nodes" <compile log>

Fix: Remove the listed operations from your host-side preprocessing.

Before:

img = img / 255.0
img = (img - mean) / std
output = ie.run(img)

After:

output = ie.run(img)   # the NPU now does /255 and normalize

Keep every step the log doesn't list (resize, letterbox, color conversion).

Verify: Detections match the original ONNX on the same image.

Applies to: DX-COM 2.4.1, dx_rt v3.4.2.

FAQ

How do I check whether the DEEPX DX-M1 is detected on my Raspberry Pi 5?

Run lspci -d 1ff4:. One line means the card is on the PCIe bus. Then run sudo ./sanity_check.sh from the driver repo; ** Sanity check PASSED! confirms the driver, device file and PCIe communication.

Do I need PCIe Gen 3 for the AI HAT?

Yes, for full NPU throughput, and on some setups the runtime doesn't see the card without it. Add dtparam=pciex1 and dtparam=pciex1_gen=3 to /boot/firmware/config.txt and reboot.

Which driver and firmware versions work with dx_rt v3.4.2?

dxrt_driver 2.5.0 or later, dx_dma 2.4.0 or later, and NPU firmware 2.7.0 or later. Models must be compiled with DX-COM 1.18.1 or later. See the version table.

Why does the driver stop working after apt full-upgrade?

A kernel update needs a DKMS rebuild of the DEEPX modules, and that rebuild needs matching kernel headers. Install linux-headers-rpi-2712 (Raspberry Pi 5), then run sudo dkms autoinstall.

Should I install the driver with DKMS or build it manually?

Use the DKMS package (dxrt-driver-dkms). It rebuilds the modules automatically on kernel updates. Manual builds put modules in a different folder and conflict with the package, so pick one method.

Why does FPS drop after a few minutes on the DEEPX DX-M1?

The NPU is most likely thermal throttling. Check the temperature with dxrt-cli -m 1 while your workload runs, and add a heatsink or fan if it keeps climbing. If FPS is low from the first frame instead, check the PCIe link speed first (see Performance and thermals).

How do I check which dx_rt, driver and firmware versions are installed?

Run dxrt-cli -s. It prints the runtime, the RT driver, the PCIe driver and the firmware versions. To check each one separately, use modinfo -F version dxrt_driver, modinfo -F version dx_dma and dxrt-cli -i (firmware). Compare the results with the version table.

Why does my app find the DEEPX DX-M1 only with sudo?

The udev rule that opens /dev/dxrt* to all users is missing. This usually follows a manual driver install. Run sudo ./install-udev_rule.sh from dx_rt_npu_linux_driver/modules, then check that ls -l /dev/dxrt0 shows crw-rw-rw-. See the full entry.

Why does my .dxnn model stop loading after a dx_rt upgrade?

dx_rt v3.4.2 only loads models compiled with DX-COM 1.18.1 or later. Recompile the original ONNX with a current DX-COM, or download the model again from the Sixfab Model Zoo.

What should I include when I ask for help with a new error?

The full terminal output, your Raspberry Pi model, uname -r, dx_rt and driver versions, and the dxrt_issue_bundle_<timestamp>.tar.gz from sudo ./sanity_check.sh. Post them in the Sixfab Community, or attach them to a support ticket if the card looks faulty.

Still stuck? Ask the community

If your error isn't on this page, post it in the Sixfab Community. Other users and the Sixfab team read it, and every new error we can reproduce is added to this page.

Include:

1. The full terminal output, not just the last line.
2. Your Raspberry Pi model and OS (cat /etc/os-release), and uname -r.
3. Whether you use the Sixfab AI HAT or the Edge AI Expansion Board.
4. The output of dxrt-cli -s, or lspci -d 1ff4: if that fails.
5. The sanity/result/dxrt_issue_bundle_<timestamp>.tar.gz file from sudo ./sanity_check.sh.

For a card that looks faulty (LED stays light blue or off with a known-good cable, or the board's PCIe interface isn't detected), open a support ticket instead.

Related: AI HAT setup guide · AI HAT troubleshooting guide · DEEPX version compatibility matrix · Sixfab Community