トラブルシューティング総合ガイド
概要
Miyabi システムで発生する一般的な問題とその解決方法を網羅したガイドです。Agent、GitHub、ビルド、デプロイ、環境設定など、あらゆる問題のトラブルシューティングを提供します。
対象読者
- すべての Miyabi ユーザー
- システム管理者
- サポートエンジニア
所要時間
- 問題ごとに 5-15 分
前提知識
- 基本的なコマンドライン操作
- Git の基礎知識
- エラーメッセージの読み方
目次
環境設定の問題
問題 1: GITHUB_TOKEN が設定されていない
症状:
Error: GITHUB_TOKEN not set
Please set GITHUB_TOKEN environment variable
原因: 環境変数が未設定
解決方法:
# .env ファイルが存在するか確認
ls -la .env
# 存在しない場合は作成
echo "GITHUB_TOKEN=ghp_your_token_here" > .env
# 環境変数を source
set -a && source .env && set +a
# または直接設定
export GITHUB_TOKEN=ghp_your_token_here
# 確認
echo $GITHUB_TOKEN
問題 2: Node.js バージョンが古い
症状:
Error: Miyabi requires Node.js 18 or higher
Current version: v16.20.0
原因: Node.js のバージョンが古い
解決方法:
# 現在のバージョン確認
node --version
# nvm を使用している場合
nvm install 20
nvm use 20
# または直接インストール
# macOS (Homebrew)
brew update
brew upgrade node
# Linux (apt)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# 確認
node --version # v20.x.x 以上
問題 3: 依存関係のインストール失敗
症状:
npm ERR! code EINTEGRITY
npm ERR! sha512-... integrity checksum failed
原因: npm キャッシュの破損
解決方法:
# npm キャッシュをクリア
npm cache clean --force
# node_modules と package-lock.json を削除
rm -rf node_modules package-lock.json
# 再インストール
npm install
# または yarn の場合
yarn cache clean
rm -rf node_modules yarn.lock
yarn install
GitHub 認証の問題
問題 4: GitHub Token のスコープ不足
症状:
Error: Your token has not been granted the required scopes
Missing scopes: read:project, write:project
原因: Token に必要な権限がない
解決方法:
# 1. Token 設定ページにアクセス
open https://github.com/settings/tokens
# 2. 該当する Token を選択
# 3. 必要なスコープを追加
# ✅ repo
# ✅ workflow
# ✅ read:project
# ✅ write:project
# 4. "Update token" をクリック
# 5. .env ファイルを更新
# （Token が変更された場合のみ）
問題 5: gh CLI と環境変数が異なる
症状: gh CLI は動作するが、Miyabi が認証エラーを出す
原因: gh CLI と GITHUB_TOKEN が別の認証を使用
解決方法:
# gh CLI の Token を環境変数に設定
export GITHUB_TOKEN=$(gh auth token)
# または .env ファイルに追加
echo "GITHUB_TOKEN=$(gh auth token)" >> .env
# 確認
gh auth status
echo $GITHUB_TOKEN
問題 6: Token の有効期限切れ
症状:
HTTP 401: Bad credentials
原因: Token が期限切れ
解決方法:
# gh CLI で再認証
gh auth refresh
# または新しい Token を作成
open https://github.com/settings/tokens
# 新しい Token を .env に設定
Agent 実行の問題
問題 7: Task tool API エラー
症状:
Error: Task tool API not available
原因: Claude Code Task tool 未実装
解決方法:
# 疑似実行モード（デフォルト）で動作確認
npm run agents:parallel:exec -- --issues=270
# デバッグログ有効化
DEBUG=agents:* npm run agents:parallel:exec -- --issues=270
問題 8: Agent が Issue を処理しない
症状: Agent が Issue を認識しない、または処理が始まらない
原因:
- Label が不足している
- Issue の形式が不適切
- GitHub Actions が無効
解決方法:
# 1. Issue の Label を確認
gh issue view 270
# 2. 手動で Label を追加
gh issue edit 270 --add-label "✨feature"
# 3. 手動で Agent を実行
npm run agents:parallel:exec -- --issues=270
# 4. GitHub Actions のステータスを確認
gh workflow list
gh workflow view agentic-system
問題 9: Agent 実行がタイムアウト
症状:
Error: Agent execution timeout after 3600000ms
原因: タスクが複雑で時間がかかっている
解決方法:
# タイムアウト時間を延長
export AGENT_TIMEOUT=7200000 # 2時間
# または Issue をより小さなタスクに分割
gh issue create --title "Subtask 1"
gh issue create --title "Subtask 2"
ビルドとテストの問題
問題 10: TypeScript コンパイルエラー
症状:
Error: Type 'string' is not assignable to type 'number'
原因: 型エラー
解決方法:
# エラー箇所を確認
npm run typecheck
# 型定義を更新
# src/types.ts を修正
# 再度チェック
npm run typecheck
# ビルド
npm run build
問題 11: ESLint エラー
症状:
Error: ESLint found 15 errors
原因: コードスタイル違反
解決方法:
# 自動修正を試みる
npm run lint -- --fix
# 手動修正が必要なエラーを確認
npm run lint
# 特定のファイルのみチェック
npx eslint src/services/authService.ts
# エラーを修正後、再度確認
npm run lint
問題 12: テストが失敗する
症状:
FAIL tests/unit/auth.test.ts
● should authenticate user
Expected: 200
Received: 401
原因: テストの期待値とコードの実装が不一致
解決方法:
# 特定のテストを実行
npm test tests/unit/auth.test.ts
# デバッグモードで実行
npm test -- --reporter=verbose
# テストコードまたは実装を修正
# 全テストを再実行
npm test
並行実行の問題
問題 13: Worktree 競合
症状:
fatal: 'worktrees/issue-270' already exists
原因: 既存 worktree が残存
解決方法:
# 既存 worktree を確認
git worktree list
# 不要な worktree を削除
git worktree remove ~/Dev/worktrees/issue-270
# 自動クリーンアップ
git worktree prune
# 再実行
npm run agents:parallel:exec -- --issues=270
問題 14: 循環依存エラー
症状:
Error: Circular dependency detected: 300 → 270 → 300
原因: Issue 間の相互依存
解決方法:
# Issue 本文から依存記述を確認
gh issue view 300
# 依存関係を修正
gh issue edit 300 --body "依存: #270のみ"
# または循環依存を無視（非推奨）
npm run agents:parallel:exec -- --issues=300 --ignore-deps
問題 15: ファイルロック競合
症状:
Error: File lock conflict on src/auth.ts
Task 1 and Task 2 cannot run in parallel
原因: 複数タスクが同じファイルを変更しようとしている
解決方法:
# 並行度を下げる
npm run agents:parallel:exec -- --issues=270,240 --concurrency=1
# または Worktree 分離モードを使用
USE_WORKTREE=true npm run agents:parallel:exec -- --issues=270,240
デプロイの問題
問題 16: ビルド失敗
症状:
Error: Build failed with exit code 1
原因: TypeScript エラーまたは依存関係の問題
解決方法:
# 依存関係を再インストール
rm -rf node_modules package-lock.json
npm install
# TypeScript エラーを確認
npm run typecheck
# エラーを修正後、再ビルド
npm run build
# 成功を確認
ls -la dist/
問題 17: ヘルスチェック失敗
症状:
Error: Health check failed after 30s
GET https://example.com returned 502
原因: デプロイ後のサービスが起動していない
解決方法:
# ヘルスチェックのタイムアウトを延長
npm run healthcheck -- --timeout 60000
# サーバーログを確認
npm run logs -- --env production
# 必要に応じてロールバック
npm run rollback:production
問題 18: Firebase デプロイエラー
症状:
Error: HTTP Error: 403, The caller does not have permission
原因: Firebase Token の権限不足
解決方法:
# Firebase に再ログイン
firebase login
# Token を取得
firebase login:ci
# 環境変数に設定
export FIREBASE_TOKEN="1//0xxx..."
# 再デプロイ
firebase deploy
Termux 特有の問題
問題 19: ロケール警告
症状:
warning: setlocale: LC_ALL: cannot change locale (ja_JP.UTF-8)
原因: Termux の制限
解決方法:
# .bashrc に追加
echo 'export LC_ALL=C' >> ~/.bashrc
echo 'export LANG=C' >> ~/.bashrc
source ~/.bashrc
影響: 機能には影響なし（警告のみ）
問題 20: Git 認証エラー
症状:
git: 'credential-!gh' is not a git command
原因: Git credential helper の設定問題
解決方法:
# Credential helper を修正
git config --global --unset-all credential.helper
git config --global credential.helper store
# gh CLI と連携
gh auth setup-git
# 確認
git config --list | grep credential
パフォーマンスの問題
問題 21: Agent 実行が遅い
症状: Agent の実行に 30 分以上かかる
原因: 並行度が低い、またはタスクが大きすぎる
解決方法:
# 並行度を上げる
npm run agents:parallel:exec -- --issues=270 --concurrency=3
# Issue をより小さなタスクに分割
gh issue create --title "Subtask 1: Login UI"
gh issue create --title "Subtask 2: Login API"
gh issue create --title "Subtask 3: Login Tests"
問題 22: メモリ不足
症状:
FATAL ERROR: Reached heap limit Allocation failed
原因: Node.js のメモリ上限
解決方法:
# Node.js のメモリ上限を増やす
export NODE_OPTIONS="--max-old-space-size=4096"
# 並行度を下げる
export DEFAULT_CONCURRENCY=1
# 不要なプロセスを終了
問題 23: ネットワークタイムアウト
症状:
Error: Network request timeout after 30000ms
原因: ネットワーク接続が不安定
解決方法:
# タイムアウト時間を延長
export NETWORK_TIMEOUT=60000
# リトライ回数を増やす
export MAX_RETRIES=5
# 安定したネットワークに接続
デバッグテクニック
ログの確認
# Agent ログ
cat .ai/logs/*.md
# 並列実行レポート
cat .ai/parallel-reports/*.json | jq
# GitHub Actions ログ
gh run list
gh run view <run-id>
# システムログ（macOS）
log show --predicate 'process == "node"' --last 1h
# システムログ（Linux）
journalctl -u node -n 100
デバッグモード
# 詳細なログ出力
DEBUG=* npm run agents:parallel:exec -- --issues=270
# 特定のモジュールのみ
DEBUG=agents:coordinator npm run agents:parallel:exec -- --issues=270
# Verbose モード
npm run agents:parallel:exec -- --issues=270 --verbose
問題の報告
問題が解決しない場合は、以下の情報を含めて Issue を作成してください：
# システム情報を収集
cat > bug-report.txt << EOF
## 環境情報
- OS: $(uname -s)
- Node.js: $(node --version)
- npm: $(npm --version)
- Miyabi: $(npm list -g miyabi)
## エラーメッセージ
$(エラーメッセージをここに貼り付け)
## 再現手順
1. ...
2. ...
3. ...
## 期待される動作
## 実際の動作
## ログ
$(cat .ai/logs/*.md | tail -n 50)
EOF
# Issue を作成
gh issue create --title "Bug: ..." --body-file bug-report.txt
関連ドキュメント
サポート
コミュニティ
よくある質問
Q: エラーメッセージが日本語と英語が混在しています A: これは正常です。システムメッセージは環境の言語設定に依存します。
Q: 問題が複数のカテゴリに該当します A: 最も関連性の高いセクションから確認してください。問題が解決しない場合は、他のセクションも確認してください。
Q: ドキュメントに載っていない問題が発生しました A: GitHub Issues で報告してください。コミュニティまたはメンテナーが対応します。
予防的メンテナンス
定期的に以下を実行して問題を予防：
# 週次メンテナンス
npm update # 依存関係更新
npm audit fix # セキュリティ修正
git gc # Git リポジトリ最適化
find .ai/logs -mtime +30 -delete # 古いログ削除
# 月次メンテナンス
npm outdated # 古いパッケージ確認
npm cache clean --force # キャッシュクリア
gh auth refresh # Token 更新
最終更新: 2025-10-10 バージョン: 2.0.0 統合元: 複数ドキュメント（AGENT_OPERATIONS_MANUAL.md, TERMUX_GUIDE.md など） メンテナー: Miyabi Support Team