Gadget 04：トラブルシューティング

Cloudflare OS を自前で動かすときによくあるトラブルを「症状 → 原因 → 対処」で整理

トラブルシューティング

ローカル（macOS）／NAS（QNAP）で動かすときによくある問題を、 症状 → 原因 → 対処の形で検索しやすく整理しました。

目的

  • 起動できない・表示されない・認証できない、を最短で解決する
  • エラーメッセージから対処への「導線」を張る

前提条件

手順（症状別の対処）

1. pnpm install が失敗する

  • 原因: Node が古い（Vite7 は Node 20.19+ / 22.12+ が必要）

  • 対処:

    nvm use 22   # 22 LTS に切り替え
pnpm install --frozen-lockfile

2. ポート 8787 が使用中（EADDRINUSE）

  • 原因: 他プロセスが 8787 を使用

  • 対処:

    lsof -i :8787     # PID を特定
kill <PID>

3. ブラウザで真っ白 / 読み込まない

  • 原因例:

    • 初回ビルドが未完了（run-local 初回は時間がかかる）
    • dist が無い / ビルド失敗

  • 対処:

    cd packages/workshop-frontend && pnpm run build
cd ../.. && pnpm run-local

4. OAuth で「Callback URL エラー」

  • 原因: 登録 URL が http のまま／ホスト・ポート不一致
  • 対処: https://<ホスト>/... を登録し、アクセス先も完全一致に

5. ログイン / 認証が失敗する

  • 原因: .dev.vars の Client ID / Secret が誤り・未設定

  • 対処:

    env | grep -i github
# 各 gatekeeper の README と注入値を照合

6. NAS の CPU 負荷が高い / ARM 機で失敗

  • 原因: arm64 のネイティブ依存（workerd / esbuild）未対応
  • 対処: x86_64 機を前提に。コンテナ上で pnpm install を先に確認

7. 外部公開したら誰でも見える

  • 原因: 既定 ADMINS=["admin"] が残存
  • 対処: 外部公開前に admin を外し、pass を強化（11-security-hardening）

8. wrangler login を要求された

  • 原因: --use-workers-ai-binding などアカウントが必要なモード
  • 対処: 通常の run-local は不要。必要時のみ wrangler login

9. 実行ログが見当たらない

  • 対処: ターミナルの wrangler ログ → .wrangler の状態 → 05-logs-cheatsheet

よくある失敗

概要 すぐやること
何が起きてるかわからない ターミナルログを tail -n 50 で確認
再現しない .wrangler と node_modules/.cache を消してクリーン再起動
前回動いたのに壊れた 20-rollback-procedure で直前状態へ戻す

確認

次に読む