FAQ トラブルシューティングガイド
このガイドは、DXNN SDK 使用中に発生する一般的なエラーと症状に対処し、段階的な解決策を提供します。
目次
- Q1. コンテナ「Restarting」エラー (#dxrtd-conflict)
- Q2. X11 セッション警告 & マウントエラー (Wayland の問題)
- Q3. ファームウェアバージョン不一致エラー
- Q4. デバイスドライバー更新エラー
- Q5. モデル・ランタイムバージョン互換性エラー
Q1. コンテナ「Restarting」エラー (dxrtd 競合)
docker_run.sh 実行後、コンテナのステータスが Restarting と繰り返し表示され、コンテナに入ることができない場合に発生します。
診断手順
- ステップ 1. ステータス確認:
docker psを実行し、STATUSがRestarting (255)を繰り返し表示しているか確認します。 - ステップ 2. ログ確認:
docker logs <container_name>を実行し、"Other instance of dxrtd is running" メッセージを確認します。
# コンテナのステータス確認
docker ps
# 出力例: STATUS が '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
# コンテナログを確認
docker logs dx-runtime-24.04
# 出力: "Other instance of dxrtd is running"
原因
DEEPX ランタイムデーモン (dxrtd) はシングルトンとして設計されています。システム全体 (ホスト + すべてのコンテナ) で実行できるインスタンスは 1 つだけです。ホストで dxrtd がすでに実行中の場合、コンテナ内のデーモンは初期化に失敗し、クラッシュループが発生します。
解決策: ホストランタイムサービス (dxrtd) の停止
方法 1: ホストサービスの停止 (推奨) ホストのサービスを停止して、コンテナ化されたデーモンが NPU の制御を取得できるようにします。
# ホストサービスを停止
sudo systemctl stop dxrt.service
# コンテナを再実行
./docker_run.sh --target=dx-runtime --ubuntu_version=24.04
詳細については、02. 環境設定の ホストシステム準備 を参照してください。
方法 2: コンテナの自動実行を防止する
ホストサービスを継続して実行する必要がある場合は、起動時にデーモン (dxrtd) が自動的に起動しないようにコンテナを設定します。
詳細については、02. 環境設定の Docker 高度なトラブルシューティング を参照してください。
Q2. X11 セッション警告 & マウントエラー (Wayland の問題)
X11 フォワーディング認証が失敗し、GUI ツールエラーまたはコンテナ起動拒否が発生する場合です。
診断手順
- Q2.1 警告: 起動中に
[WARN] it is recommended to use an X11 sessionが表示される。 - Q2.2 エラー: システム再起動またはログアウト後に
error mounting /tmp/.docker.xauthでコンテナが失敗する。
原因
- Q2.1: DX-TRON などの GUI ツールは X11 に最適化されています。Wayland セッションでは
xauthプロセスが不安定になる場合があります。 - Q2.2: Wayland セッション終了時に X 認証データが削除されるかディレクトリパスが変更され、Docker マウントポイントが無効になる場合があります。
解決策: デフォルトシステムセッションを X11 に設定する
最も信頼性の高い解決策は、ログインセッションを X11 (Xorg) に設定することです。これは Ubuntu/GNOME 環境の標準手順です。
ステップ 1. GDM 設定を修正する GDM3 設定ファイルを開きます。
sudo nano /etc/gdm3/custom.conf
WaylandEnable=false のコメントを解除して、ログイン画面が Xorg を使用するよう強制します。
# ログイン画面が Xorg を使用するよう強制
WaylandEnable=false
ステップ 2. 設定を適用する GDM を再起動するか、システムを再起動します。
sudo systemctl restart gdm3
# またはシンプルに PC を再起動
ステップ 3. リソースのクリーンアップ 再実行前に孤立コンテナを削除します。
# 既存のコンテナをクリーンアップ
docker compose -f docker/docker-compose.yml down --remove-orphans
# コンテナを再実行
./docker_run.sh --target=dx-runtime --ubuntu_version=24.04
詳細については、02. 環境設定の Docker インストール セクションを参照してください。
Q3. ファームウェアバージョン不一致エラー
NPU ハードウェアのファームウェアが必要なソフトウェアスタックバージョンより古いため、アプリケーションが停止するエラーです。
診断手順
ターミナルのエラーメッセージを確認します。
The current firmware version is X.X.X.
Please update your firmware to version Y.Y.Y or higher.
原因
インストールされた DX-RT (ランタイム) ライブラリと NPU にフラッシュされた DX-FW (ファームウェア) 間の不一致です。
解決策: ファームウェア (DX-FW) の更新とコールドブート
方法 1: 統合インストールスクリプトの使用 (推奨) オールインワン設定スクリプトを使用してファームウェアを更新します。
./dx-runtime/install.sh --target=dx_fw
方法 2: 専用 CLI ツール (dxrt-cli) の使用
特定のバイナリファイルを指定して手動でファームウェアを更新します。
dxrt-cli -u ./dx-runtime/dx_fw/m1/X.X.X/mdot2/fw.bin
重要な更新後の作業: コールドブート ハードウェアロジックを完全に初期化し、新しいファームウェアバージョンが適用されていることを確認するには、この手順に従ってください。
オプション 1. [推奨] コールドブート
- 方法: システムを完全にシャットダウンし、残留電力を排出するために電源ケーブルを抜き、その後接続して電源を入れます。
- 理由: NPU の完全なハードウェアレベルのリセットを保証する最も信頼できる方法です。
オプション 2. リモート/SSH 環境の場合
- 物理的な電源切断が不可能な場合 (例: リモートサーバールーム)、
sudo rebootコマンドで OS レベルでシステムを再起動します。ほとんどの標準的なシナリオでは、システム再起動でファームウェアを更新するのに十分です。
最終確認 再起動後、ターミナルで次のコマンドを入力してファームウェアが正常に更新されたことを確認します。
dxrt-cli -s
詳細については、02. 環境設定の ファームウェア (DX-FW) の更新とアクティベーション セクションを参照してください。
Q4. デバイスドライバー更新エラー
カーネルドライバーのバージョンが古いため、アプリケーションの実行が中断される問題です。
診断手順
ターミナルで以下のエラーメッセージを確認します。
The current device driver version is X.X.X.
Please update your device driver to version Y.Y.Y or higher.
原因
インストールされたカーネルドライバー (dx_rt_npu_linux_driver) が現在の DX-RT の最小要件を満たしていません。
解決策: ホスト OS でデバイスドライバーを更新する
これを解決するには、ホストオペレーティングシステムでドライバーモジュールを直接更新する必要があります。
ステップ 1. ドライバーモジュールのインストール ドライバーを特定のターゲットにするインストールスクリプトを実行します。
./dx-runtime/install.sh --target=dx_rt_npu_linux_driver
ステップ 2. システム再起動 ドライバーを Linux カーネルに再ロードする必要があるため、システム再起動は必須です。
sudo reboot
ステップ 3. ステータス確認 再起動後、更新が成功したことを確認します。
dxrt-cli -s
Docker コンテナはホストのカーネルを共有するため、ドライバー更新はコンテナ内ではなくホスト OS で実行する必要があります。コンテナ内でドライバーを更新してもハードウェア通信レイヤーには影響しません。
詳細については、02. 環境設定の モジュールのビルドとインストール セクションを参照してください。
Q5. モデル・ランタイムバージョン互換性エラー
コンパイラーバージョン (.dxnn ファイルの作成に使用) とランタイムライブラリバージョンの非互換性によりアプリケーションが停止するエラーです。
診断手順
ターミナルで以下のエラーメッセージを確認します。
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.
原因
DX-COM (コンパイラー) と DX-RT (ランタイム) 間のバージョン不一致が原因です。
解決策: 再コンパイルによるバージョン同期
これを解決するには、モデルとランタイム環境が互換性のあるバージョンを使用していることを確認する必要があります。
方法 1: モデルの再コンパイル (推奨)
現在のシステムの DX-RT バージョンと互換性のあるコンパイラーバージョンを使用して .dxnn ファイルを再生成します。これは最適なパフォーマンスと機能サポートを確保する最も安全な方法です。
方法 2: ランタイムライブラリバージョンの調整 モデルの要件に一致するバージョンに DX-RT を再インストールします。
この方法を選択する場合、NPU ドライバーとファームウェアの互換性も再確認する必要があります。
バージョン確認ガイド 各モジュールの正確な互換性のある組み合わせを見つけるには、DXNN SDK コンポーネントバージョン互換性マトリックス を参照してください。