For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ja/docs/tanstack/troubleshooting.md (or send Accept: text/markdown).
トラブルシューティング
セットアップ問題を実際に失敗した境界で診断する。
インストールとセットアップ
手順の前に、始める前に と ターミナルの基本 をお読みください。これらの手順では、VS Code で完全な supastack モノリポジトリを開いたことが前提となっています。そのルート package.json はリポジトリのルートをマークします。 pnpm コマンドでは、ワークスペース パッケージはアプリまたは共有コード フォルダーです。この製品では、ワークスペースはチームのデータ コンテナであり、セキュリティ境界です。 corepack pnpm --filter ... コマンドがルートから実行されている間にモノリポジトリから 1 つのパッケージを選択します。同期されたモバイル フォルダーまたはデスクトップ フォルダーのみを開いた場合、そのフォルダーには Web バックエンド、Docker セットアップ、またはルート スクリプトが含まれていません。このモノリポジトリまたはアクセス可能なホスト サーバーからバックエンドを実行し、プラットフォーム フォルダー独自のスクリプトを使用します。環境変数は、ローカルの .env ファイルまたはホスティング ダッシュボードに保存される名前付き設定です。変更後に関連するアプリを再起動し、NEXT_PUBLIC_ および EXPO_PUBLIC_ 値にサーバー シークレットが含まれないようにします。
1. 最初の有用なエラー行と、それを生成したコマンドをコピーします。シークレット値を貼り付けないでください。
2. リポジトリ ルートから、Web タイプ エラーの場合は corepack pnpm --filter @supastack/web-tanstack typecheck を実行するか、自動スイートの場合は corepack pnpm test を実行します。
3. ブラウザーの問題の場合は、corepack pnpm --filter @supastack/web-tanstack dev を使用して Web を起動し、http://localhost:3000. で再現します。 予想: 設定を変更する前に、セットアップ、コード、データベース、プロバイダー、またはブラウザーにエラーがあるかどうかを確認できます。
設定を変える前に、失敗したコマンドと最初の関連エラーを読みます。失敗が依存関係インストール、コンパイル、環境バリデーション、データベースアクセス、プロバイダーディスパッチ、ブラウザ動作のどれかを判断します。
corepack pnpm --filter @supastack/web-tanstack typecheck
corepack pnpm --filter @supastack/web-tanstack build
corepack pnpm testコピーするコマンド
コメントに従って、コマンドがどのフォルダーで実行されるかを確認します。 2 つのターミナルにラベルが付いている場合は、2 つのターミナル ウィンドウを開き、2 番目のコマンドを使用している間、最初のコマンドを実行し続けます。
corepack pnpm --filter @supastack/web-tanstack typecheck
corepack pnpm test初回実行エラーの解読
最初の実行の失敗は限られたパターンです。最初の赤いエラー行を表の行に対応させてください — 後のエラーは通常最初のエラーの結果なので、何よりも先に一番上を修正します。
| 症状 | 考えられる原因 | 最初の修正 |
|---|---|---|
| node、corepack、pnpm が認識されない / command not found | ツールがインストールされていないか、インストール完了前にターミナルが開かれていた | インストールする（またはターミナルを開き直して）から node --version を再試行する |
| package.json が見つからない / ENOENT package.json | ターミナルが間違ったフォルダーにいる | リポジトリルート（package.json を含むフォルダー）に cd して再試行する |
| EADDRINUSE / ポート 3000 がすでに使用中 | 別の開発サーバーがまだポートを保持している | そのサーバーのターミナルを見つけて Ctrl + C を押し、再度起動する |
| localhost:5432 への ECONNREFUSED またはデータベース接続エラー | Postgres が起動していない | docker compose up -d postgres を実行し、healthy になるまで待ってから再試行する |
| 欠落しているキーを指名する環境変数の検証エラー | apps/web-tanstack/.env.local がないか、必須の値が空になっている | .env.example から指名されたキーをコピーし、値を入れて保存し、サーバーを再起動する |
| corepack enable の後に corepack または pnpm が見つからない | pnpm のシムが PATH にない | corepack pnpm ... を直接使う — シムは不要です。Windows では corepack.cmd を使います |
| PowerShell が .ps1 スクリプトを実行できない / ブロックされていると言う | PowerShell のスクリプトポリシーがシムをブロックしている | .cmd 形式を使う — corepack.cmd pnpm install — ポリシーの変更は不要です |
実装ワークフロー
API アクセス欠落には、サーバーが実行中で設定済みオリジンがクライアントと一致することを確認します。利用不可な AI 選択には、AI_MODEL_POLICY と有効化されたカタログ行を検査します。キュー状態が不確かなタスクには、別の送信ではなく保存済み復旧フローを使います。
ブラウザのレイアウト問題には、計算済みスタイルを検査し正確なビューポートを再現します。製品クロームトークンは app-theme.css（catalog.ts のパック）に、マーケティングブランドロックは theme.css にあります。コンポーネントオーバーライドは詳細度で勝つことがあります。トークン宣言だけでなく描画された半径を確認してください。
検証とトラブルシューティング
ページが :3001 にある場合は、Web アプリの :3000 を開きます。 :3001 は別の apps/docs サーバーに属します。テストでデータベースへのアクセスが必要な場合は、分離された開発データベースを使用し、両方の .env の場所を確認してください。同じエラーが続く場合は、ヘルプを求めるときにコマンドとサニタイズされた最初のエラー行を含めてください。アクセスチェックを無効にしたり、シークレットをログに出力したりしないでください。
認可を無効化したり、秘密をログしたり、スキップされたインフラチェックを成功として扱ったりして失敗した検証を解決しないでください。小さな再現と関連する非機密設定を捕捉します。修正後に失敗したチェックを再実行し、次に影響を受けたリグレッションテストを実行します。