Guide/guides

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

Guren で開発しているとよく出会う問題と、その解決方法をまとめました。問題が起きたら、各パッケージのドキュメントを読む前に、まずこのページを確認してください。

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

まずは診断

最初に、組み込みの doctor コマンドで問題を自動検出します。

bunx guren doctor

doctor はルート・コントローラー・ページの整合性、足りない依存関係、設定の誤りなどを調べ、見つかった問題ごとに具体的な直し方を示します。

次にやるべきことまで含めた詳しいレポートが欲しい場合は、--next を付けて実行します。

bunx guren doctor --next

よくある問題

"Cannot find module @guren/core"

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

解決方法:

bun install

ブランチを切り替えたあとや大きな変更を取り込んだあとは、ビルドもやり直してください。

bun run build

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

原因: 前のバージョンのビルド成果物が残っていて、新しい型とぶつかっています。

解決方法:

bun run build:clean

build:clean はすべての dist/ ディレクトリを削除してから、依存関係の順にパッケージをビルドし直します。アップグレードやブランチの切り替えのあとは、必ずこちらを使ってください。

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

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

解決方法:

bun run codegen --force

--force を付けるとキャッシュを使わず、すべてのマニフェストを一から生成し直します。それでも直らない場合は、ルートファイル(routes/web.ts)がルート登録関数を正しく export しているか確認してください。

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

bun run db:migrate が cannot connect to the database at localhost:54322 (ECONNREFUSED) というエラーで失敗するケースです。

原因: Postgres コンテナが起動していないか、ポートがホストに公開されていないか、DATABASE_URL のホストやポートが間違っています。

解決方法:

データベースコンテナを起動します。
```
bun run db:up
```
db:up が導入される前に生成したプロジェクトには、このスクリプトがありません。その場合は docker compose up -d を実行するか、スクリプトを package.json に追加してください。
.env の接続文字列を確認します。
```
DATABASE_URL=postgres://guren:guren@localhost:54322/guren
```
デフォルトのポートは、システムに入っている Postgres とぶつからないよう、標準の 5432 ではなく 54322 にしています。
コンテナがポートをホストに公開しているか確認します。
```
docker compose port postgres 5432
```
0.0.0.0:54322 と表示されれば正常です。docker compose ps で Up になっていても、このコマンドが何も返さなければポートの公開に失敗しています。Docker Desktop を再起動したあとなどに起こります。次のようにコンテナを作り直してください。名前付きボリュームは残るので、データは消えません。
```
docker compose down && docker compose up -d
```

"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),
})

開発環境では、バリデーションエラーは 422 レスポンスで返り、ボディの JSON にフィールドごとのエラーが入っています。ブラウザのネットワークタブでレスポンスボディを見てください。
詳細はバリデーションを参照してください。

ルートが存在するのに "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:status
```
開発環境で一からやり直す場合は、次を実行します。
```
bunx guren db:reset
```
すべてのテーブルを削除してマイグレーションを流し直し、必要ならシードデータも投入し直します。

rule

db:reset はデータをすべて消します。開発環境以外では使わないでください。

Doctor の出力の読み方

doctor は結果を重大度ごとにまとめて表示します。

Error: 直さないとアプリが正しく動かないもの(例: 存在しないコントローラーを指しているルート)
Warning: 動きはするものの、意図しない挙動になるおそれがあるもの(例: ページコンポーネントはあるが、どのルートからも使われていない)
Info: 改善の提案(例: 使っていない import)

どの結果にも、説明とおすすめの直し方が付いています。提案どおりに直したら、bunx guren doctor をもう一度実行して、問題が消えたことを確かめてください。

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

ここまでの方法で直らない場合は、次を試してください。

node_modules を削除して入れ直します。

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

CLI リファレンスで、ほかの診断コマンドを探します。
bunx guren context でプロジェクトマップを生成し、誰かに助けを求めるときに一緒に共有します。