# セットアップのトラブルシューティング このガイドでは、Guren での開発中によく遭遇する問題とその解決方法を紹介します。何か問題が起きたときは、個別のパッケージドキュメントを読む前にまずここを確認してください。 ## まずは診断 組み込みの doctor コマンドを実行して、問題を自動的に検出します: ```bash bunx guren doctor ``` doctor はルート・コントローラー・ページの整合性、依存関係の不足、設定の問題などをチェックし、各問題に対する具体的な解決策を提示します。 推奨される次のアクションを含む詳細なレポートを表示するには: ```bash bunx guren doctor --next ``` ## よくある問題 ### "Cannot find module @guren/core" **原因:** 依存関係がインストールされていないか、ロックファイルが古い。 **解決方法:** ```bash bun install ``` ブランチの切り替えや大きな変更の取り込み後は、リビルドも実行します: ```bash bun run build ``` --- ### Guren アップグレード後の型エラー **原因:** 前バージョンの古いビルド成果物が新しい型と競合している。 **解決方法:** ```bash bun run build:clean ``` このコマンドはすべての `dist/` ディレクトリを削除し、正しい依存関係順序でパッケージを再ビルドします。アップグレードやブランチ切り替えの後は常に `build:clean` を使ってください。 --- ### コード生成が更新されない **原因:** コード生成のキャッシュが古いか、新しいルートやページが検出されていない。 **解決方法:** ```bash bun run codegen --force ``` `--force` フラグはキャッシュをバイパスし、すべてのマニフェストをゼロから再生成します。問題が解決しない場合は、ルートファイル(`routes/web.ts`)が有効なルート登録関数をエクスポートしているか確認してください。 --- ### データベースへの "Connection refused" **原因:** Postgres コンテナが起動していないか、`DATABASE_URL` のホストまたはポートが間違っている。 **解決方法:** 1. データベースコンテナを起動する: ```bash docker compose up -d ``` 2. `.env` の接続文字列を確認する: ```dotenv DATABASE_URL=postgres://guren:guren@localhost:54322/guren ``` デフォルトポートはシステムの Postgres との競合を避けるため `54322`(標準の `5432` ではない)です。 3. コンテナが正常に起動しているか確認する: ```bash docker compose ps ``` --- ### "CSRF token mismatch" **原因:** セッションミドルウェアが登録されていないか、フロントエンドが CSRF トークンをリクエストに含めていない。 **解決方法:** 1. アプリケーションのブートストラップでセッションミドルウェアが登録されていることを確認する。`add auth` ジェネレーターは自動的に設定しますが、手動でセットアップした場合は `createSessionMiddleware` がプロバイダーに含まれていることを確認してください。 2. フロントエンドでフォームが CSRF トークンを含んでいることを確認する。Inertia ページは自動的に処理します。カスタムの fetch リクエストでは、Cookie からトークンを取得して含めます: ```typescript fetch('/api/endpoint', { method: 'POST', headers: { 'X-CSRF-Token': getCsrfToken(), 'Content-Type': 'application/json', }, body: JSON.stringify(data), }) ``` 3. 詳細は [CSRF ガイド](./csrf.md) を参照してください。 --- ### バリデーションエラーの詳細が表示されない **原因:** バリデーションスキーマがリクエストボディの構造と一致していない。 **解決方法:** 1. Zod スキーマのフィールド名がフロントエンドから送信されるものと一致しているか確認する: ```typescript // フロントエンドが { userName: "..." } を送信する場合 // スキーマは username ではなく userName を使う必要がある const Schema = z.object({ userName: z.string().min(1), }) ``` 2. 開発環境では、バリデーションエラーは各フィールドのエラーをリストした JSON ボディを含む 422 レスポンスを返します。ブラウザのネットワークタブでレスポンスボディを確認してください。 3. 詳細は[バリデーション](./validation.md)を参照してください。 --- ### ルートが存在するのに "Page not found" **原因:** コード生成マニフェストが古いか、コントローラーのメソッド名がルート定義と一致していない。 **解決方法:** 1. マニフェストを再生成する: ```bash bun run codegen --force ``` 2. 整合性チェックを実行する: ```bash bunx guren check ``` 存在しないコントローラーやメソッドを参照しているルートが報告されます。 3. ルートのコントローラーメソッド名がコントローラークラスの実際のメソッドと一致しているか確認する: ```typescript // ルート router.get('/posts', [PostController, 'index']) // コントローラー — メソッド名は "index" でなければならない export class PostController extends Controller { async index() { /* ... */ } } ``` --- ### 開発サーバーは起動するがページが空白 **原因:** Vite 開発サーバーが起動していないか、SSR レンダリングがサイレントに失敗している。 **解決方法:** 1. `bun run dev` が Bun バックエンドと Vite 開発サーバーの両方を起動していることを確認する。`package.json` のスクリプトを確認してください。 2. ブラウザコンソールで JavaScript エラーを確認する。 3. SSR を使用している場合、サーバーサイドレンダリングのエラーは Bun プロセスのログに表示されます(ブラウザではなくターミナルの出力を確認してください)。 --- ### マイグレーションが "relation already exists" で失敗する **原因:** 前回のマイグレーションが途中で適用されたか、手動でテーブルを作成した。 **解決方法:** 1. マイグレーションの状態を確認する: ```bash bunx guren db:migrate:status ``` 2. 開発環境でゼロからやり直す場合: ```bash bunx guren db:reset ``` すべてのテーブルを削除し、マイグレーションを再実行し、任意でシードデータも再投入します。 > [!WARNING] > `db:reset` はすべてのデータを破壊します。開発環境でのみ使用してください。 ## Doctor の出力の読み方 `doctor` コマンドは重大度別に結果をグループ化します: - **Error** — アプリが正常に動作するために修正が必要（例: ルートが存在しないコントローラーを参照している） - **Warning** — アプリは動作するが予期しない挙動の可能性がある（例: ページコンポーネントが存在するがどのルートからも参照されていない） - **Info** — 改善の提案（例: 未使用のインポート） 各結果には説明と推奨される修正が含まれます。提案を適用した後、`bunx guren doctor` を再実行して問題が解決したことを確認してください。 ## 何をしても解決しない場合 上記のいずれでも問題が解決しない場合: 1. `node_modules` を削除して再インストールする: ```bash rm -rf node_modules bun.lock bun install bun run build:clean ``` 2. [CLI リファレンス](./cli.md)で追加の診断コマンドを確認する。 3. `bunx guren context` を実行してプロジェクトマップを生成し、助けを求める際に共有する。