トラブルシューティング (Troubleshooting)

このページでは、よく遭遇する問題やエラー状態、その原因、および復旧手順についてまとめています。ここに記載されていない問題が発生した場合は、FAQ を確認するか、FAQ の末尾に記載されているいずれかのチャンネルからお問い合わせください。

画像や動画がエディタに表示されない

症状

Load Image、Save Image、またはメディアプレビューノードに画像が表示されず、空白の領域が表示される。
ファイル自体は明らかにディスク上に存在する（例: {outputs}/images/... など）にもかかわらず、エディタに表示されない。

新しい画像をアップロードしようとすると、以下のようなエラーで失敗する：

Error: CreateStaticFileUploadUrl Failed
Description: Failed to create presigned URL for file ...: Client error
'404 Not Found' for url 'http://localhost:8124/static-upload-urls'

原因

エディタ内のメディアは、エンジンがポート 8124 で起動するローカルの静的ファイルサーバー (static file server) によって配信されます。このポートがすでに使用されている場合（多くの場合は以前起動した 2 つ目の（または孤立した）Griptape Nodes エンジンがまだバックグラウンドで動作していることが原因です）、新しく起動したエンジンの静的サーバーは、OS によって割り当てられた別のポートにフォールバックします。その結果、メディアへのリクエストが 2 つのエンジン間で分裂し、孤立したエンジンがデフォルトポートを占有し続ける一方で、実際に作業しているエンジンは別のポートから配信しようとするため、プレビューの読み込みに失敗し、アップロードが 404 エラーとなります。

解決策

まず、Ctrl+R（Windows/Linux）または Cmd+R（macOS）でエディタを再読み込みします。これで単純な表示上の不具合は解消されます。
それでもメディアが表示されない場合は、実行中のエンジンが 1 つだけであることを確認します。Griptape Nodes を完全に終了し、残存しているエンジンプロセスを探します：
- Windows: タスクマネージャーを開き、残存している Python プロセスを探して終了します。
- macOS / Linux: ターミナルで pgrep -fl griptape を実行する（またはエンジンを実行している python を探す）か、残存プロセスを停止します。
孤立したプロセスを見つけて停止できない場合は、コンピューターを再起動します。これにより、ポートを占有している残存エンジンを確実にクリアできます。
Griptape Nodes を再度起動します。クリーンな状態で起動すればエンジンプロセスは 1 つだけになり、メディアは正常に表示されます。

再起動後の確認

再起動後、ワークフローを開く前にエンジンプロセスが 1 つだけであることを確認してください。前回のセッションからの残存エンジン（特にアップデート直後）が、この問題の最も一般的な原因です。

リモートマシンでエンジンを実行している場合

エンジンがエディタとは別のマシン（またはトンネルやリバースプロキシの背後）で動作している場合、エディタに正しいアドレスを指定するまでメディアが表示されないのは正常な挙動です。静的ファイルサーバーの設定に従って static_server_base_url を設定してください。

インポートした画像や動画が 0 バイトになる

症状

インポートした画像や動画が {inputs}/images/ または {inputs}/videos/ に 0 バイト（エクスプローラーで 0 KB と表示）として保存される。
エディタにメディアが表示されず、ワークフローを再度開いてもメディアが存在しない。
Griptape Nodes を終了して再度開いても改善しない。

原因

ファイルをプロジェクトに取り込む処理は 2 つのステップで行われます。まずエンジンが空のファイルを作成して保存先ファイル名を確保し、次にエディタがポート 8124 で実行中のローカル静的ファイルサーバーにファイルの内容を送信します。この 2 番目のステップが完了しないと、確保された空のファイルだけが残ってしまいます。

これはマシン上のブラウザレベルの不具合に起因することが判明しており、Windows 10 環境でのみ確認されています。アプリケーションを再起動しても解消されません。

解決策

コンピューターを再起動してください。Griptape Nodes の再起動だけでは不十分です。

「Address already in use」/ エンジンが起動しない

症状

起動時に以下のようなエラーが表示される：

The 'websocket_direct' driver could not start: its address is already in use.
Another Griptape Nodes engine is probably already running.
Stop the other engine (or change this driver's port) and try again.

原因

別の Griptape Nodes エンジンがすでに実行されており、このエンジンが必要とするポートを占有しています。

解決策

もう一方のエンジンを停止します。他の Griptape Nodes ウィンドウを閉じ、上記のメディアセクションの手順に従って残存しているエンジンプロセスを確認・終了します。
同一マシン上で意図的に複数のエンジンを実行したい場合は、同一マシン上での複数エンジンの実行を参照してください。

同一マシン上での複数エンジンの実行

症状

同一マシン上で 2 つ以上のエンジンが実行されていると、一見無関係に見える奇妙なエラーが多数発生します。間違ったエンジンがリクエストに応答する（または二重に応答する）、エディタセッション間でワークフローや状態が混ざり合う、エディタ上で複数のエンジンが 1 つのエンジンに見える、上記のアドレス重複エラーのようなポートエラーが発生する、あるいは上記の画像読み込み問題のようにメディアの読み込みに失敗するなどの現象が起こります。

原因

ここでは 2 つの独立した問題が重なっています：

ID の競合（共通化）: GTN_ENGINE_ID が設定されていない場合、そのマシン上で起動されたすべてのエンジンは同一のデフォルトエンジン ID に解決されます。同一の ID を共有する複数のエンジンは、同じリクエストをリッスンし、同じセッション状態を共有するため、片方宛てのリクエストに両方が応答しようとします。これが大量の不可解なエラーを引き起こす原因です。
ポートの競合: 最初のエンジンがデフォルトポート（静的ファイルサーバーの 8124 など）を確保するため、後から起動したエンジンは別のポートにフォールバックし、デフォルトポートを参照し続けているコンポーネントとの連携が壊れます。

解決策

追加で起動する各エンジンに、独自の ID と独自のポート を割り当ててください：

GTN_ENGINE_ID=second-engine STATIC_SERVER_PORT=9000 GTN_MCP_SERVER_PORT=9928 gtn engine

意図して複数のエンジンを起動したわけではない場合は、上記のメディアセクションの手順に従って余分なエンジンを停止してください。

「No sessions available」— ライセンスユーザーでエンジンが起動しない

症状

（Griptape Cloud ログインではなく）ライセンス認証を使用してアクティベートしており、起動時にエンジンが No sessions available などのエラーを出してライセンスの割り当てに失敗する。

原因

組織には一定数のライセンスセッション（シート数）が割り当てられています。シートはエンジンが実行されている間保持され、エンジンが正常終了したときに解放されます。No sessions available は、プールのすべてのシートが現在使用中であることを意味します。他のユーザーが正当に使用しているか、または期限切れでない古いセッション（残存セッション）が存在することが原因です。クラッシュした、強制終了された、あるいはバックグラウンドで孤立して実行されたままのエンジンがシートを保持（および自動更新）し続けています。

解決策

クラッシュや強制終了の後は特に、上記のメディアセクションの手順に従って、自身のマシン上に孤立したエンジンプロセスがないか確認してください。それを停止すればシートが解放されます。
シートが解放されないままスタックしている場合、組織の管理者が解放できます。管理者ダッシュボードで Sessions モーダルを開き、古い残存セッションを Release（解放）してシートを空けてください。
それ以外の場合、残存セッションは期限切れになると自動的に解放されます。シートは更新が停止するとタイムアウトするため、数分待ってから再度試すことでも解決します。

「No session pool configured」エラーについて

関連するエラーとして No session pool configured が表示される場合、組織にライセンスセッションが全く構成されていないことを意味します。Griptape Nodes のライセンス管理者に連絡してください。

エディタの画面が真っ黒または真っ白になる

症状

マシンがアイドル状態やスリープ状態から復帰した後、または一時的なネットワーク切断の後に、エディタウィンドウが真っ黒または真っ白になる。

解決策

Ctrl+Shift+R（Windows/Linux）または Cmd+Shift+R（macOS）でエディタをハードリフレッシュ（強制再読み込み）します。ハードリフレッシュによりエディタが再読み込みされ、エンジンに再接続されます。

ライブラリやノードが見当たらない、または別のエンジンからのエラーが表示される

症状

ライブラリが何も表示されない、またはあるはずのノード（Agent ノードなど）が表示されない。
現在開いているものとは異なるエンジンやワークフローを参照するエラーがエディタに表示される。

原因

通常、以下のいずれかが原因です：

ライブラリの読み込みが妨げられた: ライブラリのロードに失敗した場合（依存関係の不足、破損したノードファイル、インポートエラーなど）、そのノードは通知なく非表示になります。ログがここでの唯一の情報源です。 エンジンのログを出力または開き、起動時のライブラリ読み込み周辺のエラーを確認してください。
Libraries To Register（登録ライブラリ）の設定が正しくない: エンジンは、Libraries To Register 設定（Configuration Editor → Libraries → Library Registration、griptape_nodes_config.json 内では app_events.on_app_initialization_complete.libraries_to_register として保存）に記載されているライブラリのみを読み込みます。ライブラリがそのリストにない場合、オフになっている場合、またはエントリが無効になっている場合、そのノードは表示されません。
想定とは異なるエンジンに接続されており、その別のエンジンのライブラリやエラーが表示されている可能性もあります。

解決策

まずログを確認します。 起動時のライブラリ読み込み中に出力されたエラーを探します。報告されるエラーには通常、ライブラリ名と失敗した理由が記載されています。エンジンログのエクスポートを参照してください。
エディタがどのエンジンに接続されているか確認します。複数のマシンにエンジンがある場合、エディタが意図しないエンジンに接続されている可能性があります。
Configuration Editor を開き、Libraries ビューに移動して、Library Registration → Libraries To Register を確認します。想定しているライブラリが見当たらない、オフになっている、または無効なパスを指している場合は、エントリを修正するか、Manage → Library Management → Add Library からライブラリを再度追加してください。ライブラリの有効化・無効化と削除およびライブラリのインストールを参照してください。
Libraries パネルでフィルタを Errors に切り替えて、インストールやロードに失敗したライブラリを確認します。「ライブラリをインストールしたのにノードが表示されない」を参照してください。
ライブラリが最新バージョンであることを確認します。Manage → Library Management を開き、ライブラリを展開して Check for Updates をクリックし、更新があれば Update をクリックします。ライブラリのアップデートを参照してください。エンジン本体のアップデートについては FAQ を参照してください。

「failed to locate pyvenv.cfg」/ エンジンが起動しない

症状

起動時に、エンジンが以下のエラーで起動に失敗する：

failed to locate pyvenv.cfg: The system cannot find the file specified.

原因

以前のアンインストールが完全に完了せず、Griptape Nodes の仮想環境が破損した状態で残っています。

解決策

破損したインストール環境をクリアするために、Griptape Nodes を再度アンインストールします：
```
griptape-nodes self uninstall
```
griptape-nodes コマンド自体もその仮想環境から実行されるため、仮想環境が壊れているとコマンドが起動できない場合があります。アンインストール時に同様のエラーが出る場合は、Griptape Nodes のアンインストールの手順に従って手動で削除してください。
インストール手順に従って再インストールします。

「Attempted to create a Flow with a parent 'None'」/ 通常は無害

症状

ワークフローの読み込み中や構築中に、以下のエラーが表示されることがある：

Attempted to create a Flow with a parent 'None', but no parent with that name could be found.

原因

既知の軽微なバグです。ほぼすべてのケースにおいて無害であり、作業に影響はありません。

解決策

通常はそのまま無視して作業を続けて問題ありません。
作業に支障が出ている場合は、エンジンを再起動すると解消されます。
再現手順が判明した場合は、発生に至ったコンテキストを添えてバグ報告をご提出いただけると幸いです。

「ssl.SSLCertVerificationError」/ エンジンが実行できない

症状

Griptape Nodes を実行しようとすると、以下が表示される：

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1000)

原因

マシン上の Python 環境が、検証済み SSL 証明書にアクセスできていません。

解決策

python.org のインストーラーを使用して Python を再インストールします。Griptape Nodes は Python 3.12 を必要とします。
インストールの最後に、Install Certificates を選択して実行します。
- インストーラーに表示されない場合は、/Applications/Python\ 3.12/Install\ Certificates.command を実行してください。

エンジンログのエクスポート

問題を報告する際（あるいはご自身で原因を調査する際）、エンジンのログは最初に確認すべき重要な情報源です。ただしログ単体では、どのライブラリが読み込まれたか、どの設定が有効だったか、どの API キーが設定されていたかといった状況が分からないことが多くあります。診断バンドル（Diagnostics Bundle）を作成すると、これらすべてを 1 つのステップで収集できます。

すべてを一度に収集する

診断バンドル (Diagnostics Bundle) は、以下のファイルを含む 1 つの ZIP ファイルです：

バンドル内のファイル	含まれる情報
`logs/*.log`	ディスク上に保存されたログファイル（新しい順）。先頭のファイルはバンドルを作成したセッションをカバーします。
`logs/session.log`	今回のセッションでエンジンがメモリ上に出力したすべてのログ。ログファイルへの書き込みが行われなかった場合のみ含まれます。
`report.json`	実行されていたエンジンバージョン、マシン環境、適用されていた設定、および各ライブラリとプロジェクトの読み込み結果。
`doctor.json`	`doctor` ヘルスチェック結果（検出された問題とそれぞれの対応手順）。
`workflow/`	最後に保存された状態で開かれていたワークフロー。エディタからバンドルを作成した場合のみ含まれます。
`manifest.json`	上記の全ファイルリストと、安全のために削除された機密情報の件数。
`README.md`	バンドルの内容に関する平易な説明ガイド。

診断バンドルを作成するには以下を実行します：

gtn diagnostics collect

このコマンドで作成されたバンドルには workflow/ フォルダは含まれません（コマンドが独自のエンジンを起動し、そのエンジンには開かれているワークフローがないためです）。作業中のワークフローを含めるには、エディタ上からバンドルを作成してください。

コマンドを実行すると、現在のディレクトリに griptape-nodes-diagnostics-<version>-<timestamp>.zip が出力されます。見つけやすい場所に出力したい場合は以下のように指定します：

gtn diagnostics collect --output ~/Desktop

作成されたファイルをバグ報告に添付してください。ファイルが外部に自動送信されることは一切ありません。バンドルはご自身のマシンにのみ保存され、共有するかどうかはご自身で判断できます。

除外される機密情報と、共有前の確認事項

バンドルは自身の API キーを把握しているエンジンによって生成されるため、収集するすべてのファイルを走査してそれらのキーを削除します。また、認証情報らしき文字列もすべてマスクされます。ホームディレクトリのパスは ~ に、ユーザー名は <user> に置換されます（そのまま保持したい場合は --show-identity を渡してください）。削除された箇所は <redacted> と表示され、manifest.json に削除件数が記録されるため、設定が空なのか隠されたのかを識別できます。

一方で、エンジンが事前に認識していない形式のシークレット（ノードのテキストフィールドに直接入力されたパスワードや、ライブラリが独自の形式で出力したトークンなど）は自動検出できません。バンドルを公開の場に添付する前に、logs/ 配下のファイルやワークフローファイルの内容を念のため確認してください。

ファイルを出力せず、ヘルスチェック結果のみを確認したい場合は以下を実行します：

gtn doctor

検出結果と必要な修正手順がテーブル形式で出力されます。

デスクトップアプリケーションから出力する

デスクトップアプリケーションは、自身が管理するローカルエンジン用の独自のログファイルを保持しており、現在のセッションだけでなく特定の期間（時間範囲）のログをエクスポートできます。これは、問題が少し前に発生した場合や、エンジンの再起動をまたぐ場合に特に役立ちます。

ヘッダーの Engine（エンジンの状態を示すボタン）をクリックして、エンジンポップオーバーを開きます。
Managed Engine の下にある Logs をクリックして、エンジンログウィンドウを開きます。
Export をクリックします。
Export Logs ダイアログで以下を選択します：
- Current Engine Session: エンジンが最後に起動してからのログ。
- Time Range: 特定のタイムスタンプ間のログ。From（開始時刻）と、To（終了時刻）または Now（現在）チェックボックスを指定します。問題が発生した直後であれば、セッション全体ではなく過去 30 分程度をエクスポートする方が扱いやすくなります。
.txt ファイルの保存先を選択します。

設定の要件

エクスポートを行うには、デスクトップアプリのアプリ設定にある Write engine logs to file（エンジンログをファイルに書き込む）設定が有効になっている必要があります。デフォルトで有効ですが、Export ボタンが無効になっている場合は、隣の Manage リンクをクリックして該当の設定を確認してください。

ターミナルから出力する

エンジンを手動で実行している場合（gtn または gtn engine）、ログはそのターミナルに直接出力されます。ターミナルをスクロールして該当部分をコピーしてください。

また、エンジンは独自のログファイルも保持しているため、ターミナルを開いたまま問題を見張る必要はありません。各エンジンプロセスは <XDG_DATA_HOME>/griptape_nodes/logs にファイルを書き込み、10 MB でローテーションし、1 週間アクセスのないファイルを削除します。この動作は logging.log_to_file、logging.log_directory、logging.log_retention_days の 3 つの設定で制御されます（設定リファレンスを参照）。gtn diagnostics collect を実行すれば、これらのファイルが自動的に収集されます。

ログの詳細度が不足している場合は、エンジンのログレベルを引き上げます。設定エディタ（Settings → All Settings）を開き、「log level」を検索して DEBUG に設定し、問題を再現してください（エディタでの設定編集を参照）。エディタを接続せずにヘッドレスで実行している場合は、環境変数経由で設定できます：

GTN_CONFIG_LOG_LEVEL=DEBUG gtn

メモリ上のログバッファ

エンジンは直近の 5,000 行のログをメモリ上に保持しているため、ログファイルへの書き込みが無効になっている場合でも、問題発生直後にバンドルを作成すれば logs/session.log として取得できます。エンジンがログファイルに書き込んでいた場合は、そのファイルにより多くのログが含まれているため、バンドルにはそのファイルが含まれ session.log は省略されます。いずれの場合もログレベルに応じた内容が出力されるため、デバッグ詳細が必要な場合は問題を再現する前にログレベルを DEBUG に設定してください。保持する行数は logging.session_log_buffer_lines で制御できます。