FAQ Troubleshooting Guide
本指南处理在使用 DXNN SDK 过程中发生的常见错误和症状，并提供逐步解决方案。
目录
- Q1. Container 'Restarting' Error (#dxrtd-conflict)
- Q2. X11 Session Warnings & Mount Errors (Wayland Issues)
- Q3. Firmware Version Mismatch Error
- Q4. Device Driver Update Error
- Q5. Model-Runtime Version Compatibility Error
Q1. Container 'Restarting' Error (dxrtd Conflict)
此问题是在运行 docker_run.sh 后，容器状态持续显示为 Restarting，无法进入容器的现象。
Diagnostic Steps
- Step 1. 状态确认: 运行
docker ps，确认STATUS是否反复显示Restarting (255)。 - Step 2. 日志确认: 运行
docker logs <container_name>，确认是否输出 "Other instance of dxrtd is running" 消息。
# Check container status
docker ps
# Example Output: STATUS repeats 'Restarting (255)'
CONTAINER ID IMAGE COMMAND STATUS NAMES
041b9a4933e3 dx-runtime:24.04 "/usr/local/bin/dxrtd" Restarting (255) 4 seconds ago dx-runtime-24.04
# Check container logs
docker logs dx-runtime-24.04
# Output: "Other instance of dxrtd is running"
Cause
DEEPX Runtime Demon (dxrtd) 被设计为 单例 (Singleton)。在整个系统（主机 + 所有容器）中，一次只能运行一个实例。如果主机端已经在运行 dxrtd，容器内的守护进程将初始化失败并陷入崩溃循环（crash loop）。
Solution: Stopping the Host Runtime Service (dxrtd)
Method 1: 停止主机服务（推荐）
停止主机端的服务，使容器内的守护进程获得 NPU 的控制权。
# Stop the host service
sudo systemctl stop dxrt.service
# Re-run the container
./docker_run.sh --target=dx-runtime --ubuntu_version=24.04
详细信息请参阅 02. Setting Up Environment 的 Host System Preparation。
Method 2: 防止容器内自动运行
如果需要维护主机端的服务，则配置容器使守护进程 (dxrtd) 在容器启动时不会自动启动
详细信息请参阅 02. Setting Up Environment 的 Docker Advanced Troubleshooting。
Q2. X11 Session Warnings & Mount Errors (Wayland Issues)
此问题发生在 X11 转发身份验证失败，导致 GUI 工具错误或容器启动拒绝时。
Diagnostic Steps
- Q2.1 警告: 显示
[WARN] it is recommended to use an X11 session消息。 - Q2.2 错误: 系统重启或注销后发生
error mounting /tmp/.docker.xauth挂载错误，导致容器启动失败。
Cause
- Q2.1: DX-TRON 等 GUI 工具针对 X11 进行了优化。Wayland 会话会导致 xauth 进程不稳定。
- Q2.2: 结束 Wayland 会话（如注销等）时，X 身份验证数据会被清除或目录路径会更改，导致 Docker 的挂载点无法正常工作。
Solution: Set the Default System Session to X11
最可靠的解决方案是将登录会话设置为 X11 (Xorg)。这是 Ubuntu/GNOME 环境中的标准修复程序。
Step 1. 更改 GDM 配置
打开 GDM3（GNOME Display Manager）的配置文件。
sudo nano /etc/gdm3/custom.conf
取消注释 WaylandEnable=false（删除行首的 #），设置登录屏幕强制使用 Xorg。
# Force the login screen to use Xorg
WaylandEnable=false
Step 2. 应用设置
重启 GDM 或重启系统。
sudo systemctl restart gdm3
# Or simply reboot the PC
Step 3. 资源清理
在重新运行之前，删除不需要的容器以清理状态。
# Clean up existing containers
docker compose -f docker/docker-compose.yml down --remove-orphans
# Re-run the container
./docker_run.sh --target=dx-runtime --ubuntu_version=24.04
详细信息请同时参阅 02. Setting Up Environment 的 Docker Installation 部分。
Q3. Firmware Version Mismatch Error
当写入 NPU 硬件的固件比正在使用的软件堆栈（DX-RT）要求的版本旧时，会发生此错误，导致应用程序停止。
Diagnostic Steps
确认终端中显示的错误消息。
The current firmware version is X.X.X.
Please update your firmware to version Y.Y.Y or higher.
Cause
已安装的 DX-RT（运行时）库与写入 NPU 的 DX-FW（固件）版本不匹配。
Solution: Updating Firmware (DX-FW) and Cold Booting
Method 1: 使用集成安装脚本（推荐）
使用一体化设置脚本更新固件。
./dx-runtime/install.sh --target=dx_fw
**Method 2: 使用专用 CLI 工具 (dxrt-cli) **
指定特定的二进制文件，手动进行更新。
dxrt-cli -u ./dx-runtime/dx_fw/m1/X.X.X/mdot2/fw.bin
更新后的必需操作: 冷启动 (Cold Booting)
为了完全初始化硬件逻辑并正确应用新固件，请务必执行以下步骤。
Option 1. [推荐] 冷启动 (Cold Booting)
- 步骤: 完全关闭系统，拔下电源线完全放电残留电力。然后，重新连接电缆并打开电源
- 原因: 这是确保对 NPU 进行完全硬件级重置的最可靠方法。
Option 2. 远程 / SSH 环境的情况
- ● 在物理上无法拔下电源的情况下（如远程服务器等），请在操作系统级别使用
sudo reboot命令重启系统。在标准环境中，重启可以刷新固件。
最终确认 (Final Verification)
重启后，在终端中输入以下命令，确认固件是否已正常更新。
dxrt-cli -s
详细信息请同时参阅 02. Setting Up Environment 的 Firmware (DX-FW) Update and Activation 部分。
Q4. Device Driver Update Error
此问题是由于已安装的内核驱动程序版本过旧导致应用程序执行中断的现象。
Diagnostic Steps
确认终端中是否显示以下错误消息。
The current device driver version is X.X.X.
Please update your device driver to version Y.Y.Y or higher.
Cause
当前安装的内核驱动程序（dx_rt_npu_linux_driver）不满足正在使用的 DX-RT（运行时）的最低要求。
Solution: Update the Device Driver on the Host OS
要解决此问题，需要在主机操作系统（PC 本身）端直接更新驱动程序模块。
Step 1. 安装驱动程序模块
运行针对驱动程序的安装脚本。
./dx-runtime/install.sh --target=dx_rt_npu_linux_driver
Step 2. 重启系统
由于需要将驱动程序正确重新加载到 Linux 内核中，系统重启是必需的。
sudo reboot
Step 3. 状态确认
重启后，确认更新已成功完成。
dxrt-cli -s
Docker 容器共享主机操作系统的内核。因此，驱动程序更新必须在主机操作系统上进行，而不是在容器内。尝试在容器内部更新驱动程序不会影响实际的硬件通信层。
详细信息请参阅 02. Setting Up Environment 的 Module Build and Installation 部分。
Q5. Model-Runtime Version Compatibility Error
此错误发生在用于创建 .dxnn 文件的编译器版本与执行环境的运行时库版本不兼容时导致应用程序停止的现象。
Diagnostic Steps
确认终端中是否显示以下错误消息。
The model's compiler version(X.X.X) is not compatible in this RT library.
Please downgrade the RT library version to X.X.X or use a model file generated with a compiler version X.X.X or higher.
Cause
这发生在 DX-COM（编译器）和 DX-RT（运行时）之间存在版本不匹配时。
Solution: Synchronizing Versions via Re-compilation
务必确认模型和运行时环境使用兼容的版本。
Method 1: 重新编译模型（推荐）
使用与当前系统的 DX-RT 版本兼容的编译器版本重新生成 .dxnn 文件。这是确保最佳性能和最新功能支持的最安全方法。
Method 2: 调整运行时库版本
重新安装与模型要求规范匹配的 DX-RT 版本。
如果选择此 Method，还需要重新确认 NPU 驱动程序和固件兼容性，并根据需要进行更新。
版本确认指南
有关每个模块的准确兼容性组合，请参阅 DXNN SDK 组件版本兼容性矩阵。