Guide/guides

セットアップのトラブルシューティング

このガイドでは、Guren での開発中によく遭遇する問題とその解決方法を紹介します。何か問題が起きたときは、個別のパッケージドキュメントを読む前にまずここを確認してください。

セットアップのトラブルシューティング

まずは診断

組み込みの doctor コマンドを実行して、問題を自動的に検出します:

bunx guren doctor

doctor はルート・コントローラー・ページの整合性、依存関係の不足、設定の問題などをチェックし、各問題に対する具体的な解決策を提示します。

推奨される次のアクションを含む詳細なレポートを表示するには:

bunx guren doctor --next

よくある問題

"Cannot find module @guren/core"

原因: 依存関係がインストールされていないか、ロックファイルが古い。

解決方法:

bun install

ブランチの切り替えや大きな変更の取り込み後は、リビルドも実行します:

bun run build

Guren アップグレード後の型エラー

原因: 前バージョンの古いビルド成果物が新しい型と競合している。

解決方法:

bun run build:clean

このコマンドはすべての dist/ ディレクトリを削除し、正しい依存関係順序でパッケージを再ビルドします。アップグレードやブランチ切り替えの後は常に build:clean を使ってください。

コード生成が更新されない

原因: コード生成のキャッシュが古いか、新しいルートやページが検出されていない。

解決方法:

bun run codegen --force

--force フラグはキャッシュをバイパスし、すべてのマニフェストをゼロから再生成します。問題が解決しない場合は、ルートファイル(routes/web.ts)が有効なルート登録関数をエクスポートしているか確認してください。

データベースへの "Connection refused"

原因: Postgres コンテナが起動していないか、DATABASE_URL のホストまたはポートが間違っている。

解決方法:

データベースコンテナを起動する:

docker compose up -d

.env の接続文字列を確認する:

DATABASE_URL=postgres://guren:guren@localhost:54322/guren

デフォルトポートはシステムの Postgres との競合を避けるため 54322(標準の 5432 ではない)です。

コンテナが正常に起動しているか確認する:
```
docker compose ps
```

"CSRF token mismatch"

原因: セッションミドルウェアが登録されていないか、フロントエンドが CSRF トークンをリクエストに含めていない。

解決方法:

アプリケーションのブートストラップでセッションミドルウェアが登録されていることを確認する。add auth ジェネレーターは自動的に設定しますが、手動でセットアップした場合は createSessionMiddleware がプロバイダーに含まれていることを確認してください。

フロントエンドでフォームが CSRF トークンを含んでいることを確認する。Inertia ページは自動的に処理します。カスタムの fetch リクエストでは、Cookie からトークンを取得して含めます:

fetch('/api/endpoint', {
  method: 'POST',
  headers: {
    'X-CSRF-Token': getCsrfToken(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
})

詳細は CSRF ガイドを参照してください。

バリデーションエラーの詳細が表示されない

原因: バリデーションスキーマがリクエストボディの構造と一致していない。

解決方法:

Zod スキーマのフィールド名がフロントエンドから送信されるものと一致しているか確認する:

// フロントエンドが { userName: "..." } を送信する場合
// スキーマは username ではなく userName を使う必要がある
const Schema = z.object({
  userName: z.string().min(1),
})

開発環境では、バリデーションエラーは各フィールドのエラーをリストした JSON ボディを含む 422 レスポンスを返します。ブラウザのネットワークタブでレスポンスボディを確認してください。
詳細はバリデーションを参照してください。

ルートが存在するのに "Page not found"

原因: コード生成マニフェストが古いか、コントローラーのメソッド名がルート定義と一致していない。

解決方法:

マニフェストを再生成する:

bun run codegen --force

整合性チェックを実行する:
```
bunx guren check
```
存在しないコントローラーやメソッドを参照しているルートが報告されます。

ルートのコントローラーメソッド名がコントローラークラスの実際のメソッドと一致しているか確認する:

// ルート
router.get('/posts', [PostController, 'index'])

// コントローラー — メソッド名は "index" でなければならない
export class PostController extends Controller {
  async index() { /* ... */ }
}

開発サーバーは起動するがページが空白

原因: Vite 開発サーバーが起動していないか、SSR レンダリングがサイレントに失敗している。

解決方法:

bun run dev が Bun バックエンドと Vite 開発サーバーの両方を起動していることを確認する。package.json のスクリプトを確認してください。
ブラウザコンソールで JavaScript エラーを確認する。
SSR を使用している場合、サーバーサイドレンダリングのエラーは Bun プロセスのログに表示されます(ブラウザではなくターミナルの出力を確認してください)。

マイグレーションが "relation already exists" で失敗する

原因: 前回のマイグレーションが途中で適用されたか、手動でテーブルを作成した。

解決方法:

マイグレーションの状態を確認する:

bunx guren db:migrate:status

開発環境でゼロからやり直す場合:
```
bunx guren db:reset
```
すべてのテーブルを削除し、マイグレーションを再実行し、任意でシードデータも再投入します。

Warning

db:reset はすべてのデータを破壊します。開発環境でのみ使用してください。

Doctor の出力の読み方

doctor コマンドは重大度別に結果をグループ化します:

Error — アプリが正常に動作するために修正が必要（例: ルートが存在しないコントローラーを参照している）
Warning — アプリは動作するが予期しない挙動の可能性がある（例: ページコンポーネントが存在するがどのルートからも参照されていない）
Info — 改善の提案（例: 未使用のインポート）

各結果には説明と推奨される修正が含まれます。提案を適用した後、bunx guren doctor を再実行して問題が解決したことを確認してください。

何をしても解決しない場合

上記のいずれでも問題が解決しない場合:

node_modules を削除して再インストールする:

rm -rf node_modules bun.lock
bun install
bun run build:clean

CLI リファレンスで追加の診断コマンドを確認する。
bunx guren context を実行してプロジェクトマップを生成し、助けを求める際に共有する。