トラブルシューティング

このページでは、セルフホスティングの Nodaro でよくある問題を、症状と対処法の組み合わせで紹介します。まずは /setup ページを確認してください。ほとんどの問題は、このページでひと目でわかります。

まず /setup を確認する

セルフホスティング環境では、http://<your-host>/setup にリアルタイムの状態画面があります。ログインは不要で、各部分が存在し、動作しているかどうかだけを表示します。シークレットが表示されることはありません。

• カード：データベース、Redis、ストレージ、暗号化キー、プロバイダーキーのカードが、緑か赤で表示されます。データベースのカードには、独自のマイグレーション未適用の状態があります。
• ヒント：問題のあるカードにはそれぞれヒントが表示され、確認すべき変数を示します。
• リアルタイムの更新：このページは 5 秒ごとに再確認します。

ページに「API に接続できません」と表示される場合、Web サーバーは動いていますが、API が応答していません。docker compose -f docker-compose.community.yml logs -f でコンテナのログを確認し、ポート 3000 を妨げているものがないか確認してください。

環境が起動しない

起動時に Missing or invalid env vars と表示される。メッセージには、検証に失敗した変数が一覧表示されます。よくある原因は、SUPABASE_SERVICE_ROLE_KEY が空であることと、INTERNAL_ORCHESTRATOR_SECRET が 32 文字より短いことです。

docker compose up で port is already allocated と表示される。スタックが公開するホストポートは、アプリ用の 3000 と、MinIO コンソール用の 9001（ループバックのみ）の 2 つだけです。Redis とデータベースは、ホストのポートを使いません。docker-compose.community.yml で、競合しているポートマッピングのホスト側を変更してください（たとえば "3001:3000"）。アプリのポートを変更した場合は、PUBLIC_URL もそれに合わせて設定します。

起動時にマイグレーションが失敗した。アプリのログに、失敗したファイルの名前が表示されます。API は、マイグレーションが途中までしか適用されていないデータベースでは起動しません。原因を修正して、docker compose -f docker-compose.community.yml up をもう一度実行してください。適用済みのファイルはスキップされます。

ログインサービスのログに password authentication failed for user "supabase_auth_admin" と表示される。db-data ボリュームがデータベースのロール設定より古いか、初回起動後に POSTGRES_PASSWORD を変更しています。ロールのパスワードが POSTGRES_PASSWORD に合わせて設定されるのは、初回起動時だけです。docker compose -f docker-compose.community.yml down -v でボリュームを削除するか（データが削除されます）、supabase_admin としてロールのパスワードを手動で変更してください。

Docker のビルドで、ffmpeg のアーカイブのダウンロードか検証に失敗する。これは、イメージを自分でビルドする場合にだけ起こります。レンダリングされるオーディオや動画は ffmpeg のバージョンによって変わるため、Dockerfile では ARG FFMPEG_TARBALL_URL_* と ARG FFMPEG_TARBALL_SHA256_* を使って、アーキテクチャごとに特定の静的 ffmpeg ビルドを固定しています。ダウンロードの失敗やチェックサムの不一致があると、出力が知らないうちに変わるのを防ぐため、ビルドが停止します。同じビルドの、より新しい日付のリリース（GitHub の BtbN/FFmpeg-Builds）を選び、両方のアーキテクチャについて、URL と SHA-256 の両方を更新してください。これは実際の ffmpeg のアップグレードとして扱い、そのあとでレンダリング結果を確認してください。

ブラウザーにエラーが表示される

エディターは表示されるが、空白のまま、または「読み込み中…」のまま進まない。ブラウザーのコンソールを開いてください。

• CORS エラーの場合：次の項目を参照してください。
• ログインのエラーの場合：環境の /config.js を開きます。このファイルには、ブラウザーからアクセスできる Supabase の URL（同梱のスタックでは PUBLIC_URL/supabase）と、anon キーが記載されている必要があります。コンテナは起動時に、PUBLIC_URL、FRONTEND_SUPABASE_URL、SUPABASE_ANON_KEY からこのファイルを書き込みます。これらを修正して、再起動してください。

ブラウザーに CORS エラーが表示される。http://localhost:3000 と PUBLIC_URL は常に許可されているため、LAN のアドレスや別のポートなど、ほかのオリジンでアプリを開いています。PUBLIC_URL をそのオリジンに設定するか、追加のオリジンをカンマ区切りで CORS_ORIGIN に列挙してください（たとえば CORS_ORIGIN=http://192.168.1.20:3000）。そのあと、docker compose -f docker-compose.community.yml up -d を実行します。

動画編集（Edit video）で、エディターの代わりにパネルが表示される。ホスティング版の動画エディターは、http://localhost:3000 からの埋め込みしか受け付けません。ほかのオリジンでは、自分でエディターを運用して FREECUT_URL を設定してください。動画とオーディオのエディターを参照してください。

オーディオ編集（Edit audio）で、エディターの代わりにパネルが表示される。ホスティング版のオーディオエディターはありません。自分で AudioMass を運用して、AUDIOMASS_URL を設定してください。

データベース

マイグレーションが「relation … does not exist」で失敗する。マイグレーションが順番どおりに実行されませんでした。Supabase の SQL エディターなどで、supabase/migrations/ のファイルをファイル名の順に適用してください。各ファイルは、すでに適用済みのデータベースで再実行しても問題ありません。

OAuth のコールバックが 500 を返す。マイグレーションが適用されていないため、OAuth アプリ用のテーブルがありません。すべてのマイグレーションを、ファイル名の順に適用してください。データベースを参照してください。

API が再起動を繰り返す。API が Postgres に接続できていません。データベースが停止している間は、この動作は想定どおりです。Postgres が復旧したら、docker compose -f docker-compose.community.yml restart nodaro を実行してください。

ストレージ

同梱のスタックで、アップロードが失敗する。http://localhost:9001 で MinIO コンソールを開きます。デフォルトの認証情報は、Compose ファイルに記載されています。

Cloudflare R2 へのアップロードが 401 か 403 を返す。API トークンに、そのバケットに対する Object Read & Write の権限があることを確認してください。R2 の前段にカスタムドメインを置いている場合は、バケットの公開アクセスの設定も確認します。Nodaro はブラウザーに公開のメディア URL を渡すため、認証なしで読み取れる必要があります。

ストレージへのリクエストが、すべて認可のエラーかエンドポイントのエラーで失敗する。R2_REGION に、ストレージのリージョンを設定してください。AWS、DigitalOcean Spaces、ローカルの Supabase はデフォルトの auto を受け付けず、そのエラーメッセージにはリージョンのことが書かれていません。

STORAGE_OBJECT_ACL を設定したあと、すべてのアップロードが失敗する。ストレージのキーに、オブジェクトの ACL を設定する権限がありません。ストレージがバケットポリシーを受け付けない場合を除き、この変数は空のままにしてください。

R2 を使っていて、起動ログに [storage] failed to create bucket と表示される。問題はありません。R2 のトークンはバケットを作成できませんが、バケットはすでに存在しています。

実行とノード

ワークフローがキューに入ったまま、実行が始まらない。docker compose -f docker-compose.community.yml logs nodaro でログを確認します。オーケストレーターは Redis から処理を受け取るため、Redis に接続できないと何も実行されません。REDIS_URL を確認し、docker compose -f docker-compose.community.yml exec redis redis-cli ping を実行してください。PONG と返れば正常です。

ノードが Missing API key で失敗する。ノードが、キーのないプロバイダーを呼び出しています。/setup か .env でキーを追加してください。プロバイダーキーを参照してください。

画像と動画は動くが、テキストの機能がすべて失敗する。KIE_API_BASE_URL に、メディアのパスだけを転送するプロキシが指定されています。プロバイダーへの通信を自前のプロキシ経由にするを参照してください。

キーの貼り付けや Nodaro Cloud への接続が EncryptionKeyMissingError で失敗する。環境に暗号化キーがありません。マネージドの Supabase プロジェクトを使う場合は、NODARO_ENCRYPTION_KEY に、openssl rand -hex 32 で生成した 64 文字の 16 進数を設定してください。

復元後に、プロバイダーキーが missing と表示される。対応する暗号化キーなしで、データベースが復元されています。バックアップと復元を参照してください。

ノードが 503 nodaro_connection_required で失敗する。このノードは Nodaro 専用ノードで、Nodaro Cloud への接続が必要です。Nodaro Cloud への接続を参照してください。

Cloud 経由の実行が Token expired で失敗する。接続の 90 日間有効なトークンが期限切れになりました。接続を解除をクリックしてから、接続をクリックします。

Cloud 経由の実行が 402 instance_cap_reached で失敗する。環境が月間の使用上限に達しました。app.nodaro.ai の請求 › 接続済みのインスタンスで、上限を引き上げてください。

正常な実行が Execution orphaned として扱われる。2 つの環境が、別々の Redis を使いながら 1 つのデータベースを共有しています。環境ごとに固有の RUNTIME_ENV を設定してください。スケーリングを参照してください。

3D レンダリング Pro（3D Render Pro）が 503 SCENE_CAPABILITY_UNAVAILABLE を返す。3D レンダリング Pro はホスティングされたビルドサービス上で動作し、セルフホスティング型のエディションには含まれません。ほかのレンダラーに黙って切り替わることはありません。自分のサーバーで動作する 3D シーン生成（Generate 3D Scene）と動画レンダリング（Render Video）を使ってください。

ログインと MCP

SSO のルートが 404 unknown_provider を返す。プロバイダーが設定されていません。EXTERNAL_SSO_PROVIDERS を確認してください。Compose スタックでは、この変数を nodaro サービスの environment: に追加します。シングルサインオンを参照してください。

すべての API 呼び出しが 403 sso_required を返す。サーフェスプロファイルで SSO だけが許可されていて、アカウントが SSO を通じて作成またはリンクされていません。ログイン方法を参照してください。

MCP クライアントが 405 wrong_mcp_host を受け取る。クライアントが、アプリのメインのアドレスを使っています。代わりに、MCP ホストのアドレスを指定してください。MCP を参照してください。

アップデート

バージョン表示に組み込みのバージョンしか表示されず、リリースノートが空になっている。更新チェックが GitHub を読み取れていません。ログに [update-check] … read failed: HTTP 403 (rate limit: 0 of 60 left…) という行がある場合は、送信元アドレスが GitHub の匿名リクエストの上限を使い切っています。NODARO_UPDATE_CHECK_TOKEN を設定してください。アップデートを参照してください。

サポートを受ける

それでも解決しない場合は、アプリのコンテナの Docker ログを添えて、GitHub で Issue を作成してください。