ProductReadyProductReady

トラブルシューティング

一般的な問題とその解決方法 - すぐに問題を解決

トラブルシューティング

困っていますか？このガイドでは、一般的な問題とその解決方法をカバーしています。

問題が見つかりませんか？ GitHub Issuesを検索するか、Discussionsで質問してください。

インストールの問題

pnpm install後に「Module not found」

症状：インポートエラー、TypeScriptがモジュールを見つけられない

解決策：

# すべてをクリアして再インストール
rm -rf node_modules .next pnpm-lock.yaml
pnpm install

# 開発サーバーを再起動
pnpm dev

「pnpm not found」

解決策：pnpmをグローバルにインストール

npm install -g pnpm

# またはCorepackを使用（推奨）
corepack enable
corepack prepare pnpm@latest --activate

「Node version too old」

症状：構文エラーでビルドが失敗

解決策：Node.js 24.18.0 LTSにアップグレード

# 現在のバージョンを確認
node -v

# 最新のLTSをインストール（nvmを使用）
nvm install --lts
nvm use --lts

データベースの問題

「Database connection failed」

これらを確認：

  1. PG_DATABASE_URLは設定されていますか？

    echo $PG_DATABASE_URL
# 表示されるべき: postgresql://...

  2. フォーマットは正しいですか？

    # 正しいフォーマット:
postgresql://user:password@host:5432/database

  3. 手動で接続できますか？

    psql $PG_DATABASE_URL

解決策：

  • .envファイルが存在し、正しい変数が含まれていることを確認
  • データベースサーバーが実行中であることを確認
  • ファイアウォールがポート5432をブロックしていないことを確認

「Relation does not exist」

症状：クエリ時に「relation "users" does not exist」

解決策：マイグレーションを実行

pnpm db:push

「Column does not exist」

症状：「column "email" does not exist」

解決策：

  1. スキーマを更新：src/db/schema/
  2. データベースにプッシュ：pnpm db:push
  3. サーバーを再起動

認証の問題

セッションが持続しない

症状：ログイン後、リフレッシュでログアウト

解決策：

  1. BETTER_AUTH_SECRETが.envに設定されていることを確認

    # 生成:
openssl rand -base64 32

  2. 開発ではlocalhostを使用（127.0.0.1ではなく）

  3. Cookieが設定されていることを確認（DevToolsをチェック）

OAuthリダイレクトが機能しない

症状：GitHub/Googleログイン後に404

解決策：

  1. OAuthプロバイダーのコールバックURLを確認

    http://localhost:3000/api/auth/callback/github

  2. .envに正しいクライアントID/シークレットがあることを確認

  3. サーバーを再起動

「Invalid credentials」

症状：正しいパスワードでもログインできない

解決策：

  1. メールアドレスが正しいことを確認（大文字小文字を区別）
  2. データベースでユーザーが存在することを確認
  3. パスワードハッシュが保存されていることを確認

ビルドの問題

「Type error」during build

症状：pnpm buildがTypeScriptエラーで失敗

解決策：

  1. 型を生成：

    pnpm db:generate
pnpm i18n:typegen

  2. TypeScriptサーバーを再起動（VSCode）

  3. 開発で型チェック：

    pnpm typecheck

「Module not found」during build

解決策：

# 依存関係を再インストール
rm -rf node_modules .next
pnpm install
pnpm build

「Out of memory」

症状：ビルド時にメモリ不足

解決策：

# Node.jsのメモリを増やす
export NODE_OPTIONS="--max-old-space-size=4096"
pnpm build

開発サーバーの問題

「Port 3000 already in use」

解決策：

# ポートを使用しているプロセスを見つける
lsof -i :3000

# プロセスを強制終了
kill -9 <PID>

# または別のポートを使用
pnpm dev -- -p 3001

ホットリロードが機能しない

症状：ファイルを変更してもページが更新されない

解決策：

  1. .nextフォルダを削除：

    rm -rf .next
pnpm dev

  2. ファイルウォッチャーの制限を増やす（Linux）：

    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

変更が遅い

症状：ファイル保存後、更新に時間がかかる

解決策：

  1. node_modulesをウイルススキャナーから除外
  2. Docker使用時は、コードをコンテナ内にコピー（マウントしない）
  3. WSL2を使用（Windowsの場合）

tRPCの問題

「tRPC error: Unauthorized」

症状：保護されたルートが401を返す

解決策：

  1. ログインしていることを確認
  2. セッションCookieが設定されていることを確認
  3. tRPCクライアントが正しく設定されていることを確認

「Query key not found」

症状：React Queryエラー

解決策：

  1. src/server/index.tsでルーターがエクスポートされていることを確認
  2. サーバーを再起動
  3. ブラウザキャッシュをクリア

Vercelデプロイの問題

「Build failed」on Vercel

解決策：

  1. ログでエラーを確認
  2. すべての環境変数が設定されていることを確認
  3. ローカルでpnpm buildを実行してテスト

「Database connection timeout」

症状：デプロイ後、データベース接続エラー

解決策：

  1. データベースがVercelからアクセス可能であることを確認

  2. 接続プールを設定：

    // drizzle.config.ts
pool: {
  min: 2,
  max: 10,
}

  3. データベースプロバイダーのファイアウォール設定を確認

パフォーマンスの問題

ページ読み込みが遅い

診断：

# 本番ビルドでテスト
pnpm build
pnpm start

解決策：

  1. 画像を最適化（Next.js Imageを使用）

  2. バンドルサイズを確認：

    pnpm build --analyze

  3. 不要なインポートを削除

データベースクエリが遅い

解決策：

  1. インデックスを追加：

    // schema
index("user_email_idx").on(users.email)

  2. EXPLAIN ANALYZEでクエリを分析

  3. N+1クエリを避ける（データローダーを使用）

よくある質問

デモモードを無効にするには？

解決策：

// lib/demo.ts
export const isDemoMode = () => false;

データベースをリセットするには？

警告：すべてのデータが削除されます！

pnpm db:push --force
pnpm db:seed

Stripeテストモードから本番に切り替えるには？

解決策：

  1. Stripeダッシュボードで本番キーを取得

  2. .envを更新：

    STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...

  3. Webhookエンドポイントを更新

それでも問題が解決しない場合

コミュニティに助けを求める

  1. GitHub Issues：問題を報告
  2. Discussions：質問する
  3. ドキュメント：関連ガイドを検索

デバッグ情報を提供

問題を報告する際は、以下を含めてください：

  • ✅ エラーメッセージ（完全なスタックトレース）
  • ✅ 再現手順
  • ✅ Node.js、pnpm、OSバージョン
  • ✅ 関連する設定ファイル

予防のヒント

開発のベストプラクティス

  • ✅ 定期的に更新：pnpm update
  • ✅ 依存関係を最小限に：本当に必要なものだけをインストール
  • ✅ 環境変数を使用：シークレットをコードにハードコードしない
  • ✅ 型チェック：コミット前にpnpm typecheck
  • ✅ 頻繁にテスト：早期に問題をキャッチ

次のステップ

問題を解決したら：

  1. デプロイ - 本番環境に配信
  2. パフォーマンス - アプリを最適化
  3. ベストプラクティス - 品質基準を学ぶ

このガイドが役に立ちましたか？ フィードバックを共有したり、改善を提案したりしてください！ 💪

Product Ready Standards

Production-ready quality standards and best practices for ProductReady - build it right the first time

/api/v1/health

API documentation for /api/v1/health

On this page

トラブルシューティングインストールの問題pnpm install後に「Module not found」「pnpm not found」「Node version too old」データベースの問題「Database connection failed」「Relation does not exist」「Column does not exist」認証の問題セッションが持続しないOAuthリダイレクトが機能しない「Invalid credentials」ビルドの問題「Type error」during build「Module not found」during build「Out of memory」開発サーバーの問題「Port 3000 already in use」ホットリロードが機能しない変更が遅いtRPCの問題「tRPC error: Unauthorized」「Query key not found」Vercelデプロイの問題「Build failed」on Vercel「Database connection timeout」パフォーマンスの問題ページ読み込みが遅いデータベースクエリが遅いよくある質問デモモードを無効にするには？データベースをリセットするには？Stripeテストモードから本番に切り替えるには？それでも問題が解決しない場合コミュニティに助けを求めるデバッグ情報を提供予防のヒント開発のベストプラクティス次のステップ