mergegate/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Miyabi使用中に発生する可能性のある問題と解決策をまとめています。

🔧 環境関連

GITHUB_TOKENが設定されていない

症状:

Error: GITHUB_TOKEN not set

解決策:

1. トークンを取得: https://github.com/settings/tokens/new
2. 環境変数を設定:

   export GITHUB_TOKEN=ghp_xxxxx
   

3. シェルプロファイルに追加（永続化）:

   echo 'export GITHUB_TOKEN=ghp_xxxxx' >> ~/.zshrc
   source ~/.zshrc
   

ANTHROPIC_API_KEYが設定されていない

症状:

Error: ANTHROPIC_API_KEY not set

解決策:

1. Anthropic Consoleでキー取得: https://console.anthropic.com/
2. 環境変数を設定:

   export ANTHROPIC_API_KEY=sk-ant-xxxxx
   

🐛 Git関連

Git repositoryが見つからない

症状:

Error: Not a git repository

解決策:

cd your-project
git init

Worktreeが残ったまま

症状:

Error: Worktree already exists: .worktrees/issue-123

解決策:

# Worktree一覧確認
git worktree list

# 不要なWorktreeを削除
git worktree remove .worktrees/issue-123

# すべてのstale Worktreeをクリーンアップ
git worktree prune

マージコンフリクト

症状:

CONFLICT (content): Merge conflict in src/main.rs

解決策:

# コンフリクトファイルを確認
git status

# 手動でコンフリクトを解決
# エディタでファイルを開き、<<<<<<<, =======, >>>>>>> マーカーを削除

# 解決後
git add src/main.rs
git commit -m "fix: resolve merge conflict"

🤖 Agent関連

Agent実行が失敗する

症状:

Error: Agent execution failed

解決策:

1. ログファイル確認:

   tail -f logs/miyabi-$(date +%Y%m%d).log
   

2. Issue番号が正しいか確認:

   gh issue list
   

3. Labelが正しく設定されているか確認

Issue番号が見つからない

症状:

Error: Issue #123 not found

解決策:

# Issue一覧確認
gh issue list --limit 50

# 正しい番号で再実行
miyabi agent run coordinator --issue 正しい番号

📦 インストール関連

miyabi コマンドが見つからない

症状:

command not found: miyabi

解決策:

# crates.ioから再インストール
cargo install miyabi-cli --force

# パス確認
which miyabi

# Cargo binディレクトリがPATHに含まれているか確認
echo $PATH | grep -o "$HOME/.cargo/bin"

# なければ追加
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

コンパイルエラー

症状:

error: failed to compile miyabi-cli

解決策:

# Rustを最新版にアップデート
rustup update stable

# Cargoキャッシュをクリア
rm -rf ~/.cargo/registry
rm -rf ~/.cargo/git

# 再インストール
cargo install miyabi-cli

🌐 GitHub関連

API Rate Limit

症状:

Error: API rate limit exceeded

解決策:

1. GitHubにログイン状態か確認:

   gh auth status
   

2. Personal Access Tokenのスコープ確認
3. しばらく待つ（Rate limitは1時間でリセット）

Permission denied

症状:

Error: Resource not accessible by personal access token

解決策:

1. トークンのスコープを確認: repo, workflow が必要
2. 新しいトークンを生成
3. 環境変数を更新

🔍 デバッグ方法

詳細ログを有効化

.miyabi.yml でログレベルを変更:

logging:
  level: debug  # info → debug
  directory: "./logs"

ログファイルの確認

# 最新のログ
tail -100 logs/miyabi-$(date +%Y%m%d).log

# エラーのみ抽出
grep -i "error\|fail" logs/miyabi-*.log

# 特定のAgentのログ
grep -i "CoordinatorAgent" logs/miyabi-*.log

miyabi status の活用

miyabi status

# 出力例:
# Miyabi Installation: ✅ or ❌
# Environment: GITHUB_TOKEN, ANTHROPIC_API_KEY の状態
# Git Repository: ブランチ、コミット状態
# Worktrees: アクティブなWorktree数

🆘 それでも解決しない場合

サポートを受ける

1. GitHub Issues: https://github.com/ShunsukeHayashi/Miyabi/issues

   • 詳細なエラーメッセージを含めてください
   • miyabi status の出力を添付
   • ログファイルの関連部分を添付

2. Discord Community: （準備中）

3. ドキュメント:

   • GETTING_STARTED.md
   • CLAUDE.md
   • GitHub Discussions

報告に含めるべき情報

# システム情報
uname -a

# Rustバージョン
rustc --version
cargo --version

# miyabiバージョン
miyabi --version

# プロジェクト状態
miyabi status

# 直近のログ
tail -50 logs/miyabi-$(date +%Y%m%d).log

---

Miyabi - Beauty in Autonomous Development 🌸