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/web/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 typecheck を実行するか、自動スイートの場合は corepack pnpm test を実行します。

3. ブラウザーの問題の場合は、corepack pnpm --filter @supastack/web dev を使用して Web を起動し、http://localhost:3000. で再現します。予想: 設定を変更する前に、セットアップ、コード、データベース、プロバイダー、またはブラウザーにエラーがあるかどうかを確認できます。

設定を変える前に、失敗したコマンドと最初の関連エラーを読みます。失敗が依存関係インストール、コンパイル、環境バリデーション、データベースアクセス、プロバイダーディスパッチ、ブラウザ動作のどれかを判断します。

corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm test

コピーするコマンド

コメントに従って、コマンドがどのフォルダーで実行されるかを確認します。 2 つのターミナルにラベルが付いている場合は、2 つのターミナルウィンドウを開き、2 番目のコマンドを使用している間、最初のコマンドを実行し続けます。

corepack pnpm --filter @supastack/web 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/.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 の場所を確認してください。同じエラーが続く場合は、ヘルプを求めるときにコマンドとサニタイズされた最初のエラー行を含めてください。アクセスチェックを無効にしたり、シークレットをログに出力したりしないでください。

認可を無効化したり、秘密をログしたり、スキップされたインフラチェックを成功として扱ったりして失敗した検証を解決しないでください。小さな再現と関連する非機密設定を捕捉します。修正後に失敗したチェックを再実行し、次に影響を受けたリグレッションテストを実行します。