本文へスキップ

FAQ Troubleshooting Guide

このガイドでは、DXNN SDK の使用中に発生する一般的なエラーや症状を扱い、ステップバイステップの解決策を提供します。

目次

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)**として設計されています。 システム全体（ホスト ＋ すべてのコンテナ）で、一度に実行できるインスタンスは1つだけです。 ホスト側ですでに 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構成の変更
GDM3GNOME 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環境の場合

  • ● 物理的に電源を抜くことが不可能な場合（リモートサーバーなど）は、OSレベルで 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​

この問題を解決するには、ホスト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ユーザーへの重要な注意

DockerコンテナはホストOSのカーネルを共有しています。 そのため、ドライバの更新はコンテナ内ではなく、必ずホストOS上で行ってください。 コンテナ内部でドライバを更新しようとしても、実際のハードウェア通信レイヤーには影響を与えません。

詳細については 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 を再インストールします。

Note

このMethodを選択する場合、NPUドライバとファームウェアの互換性も併せて再確認し、必要に応じてアップデートする必要があります。

バージョン確認ガイド
各モジュールの正確な互換性の組み合わせについては、DXNN SDK コンポーネントバージョン互換性マトリックスを参照してください。

Last updated: