Tree-sitter Analyzer トラブルシューティングガイド

November 28, 2025 · View on GitHub

概要

このガイドでは、Tree-sitter Analyzerの使用中に発生する可能性のある一般的な問題と、その解決方法について説明します。特に、新しく実装されたログ設定改善機能に関連する問題に焦点を当てています。

🚨 一般的な問題と解決方法

1. MCPサーバー関連の問題

問題: MCPサーバーが起動しない

症状:

Claude DesktopでMCPサーバーが認識されない
"Server not available" エラーが表示される

解決手順:

ログを有効化して詳細を確認:

{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uvx",
      "args": [
        "--from", "tree-sitter-analyzer[mcp]",
        "tree-sitter-analyzer-mcp"
      ],
      "env": {
        "TREE_SITTER_ANALYZER_ENABLE_FILE_LOG": "true",
        "TREE_SITTER_ANALYZER_FILE_LOG_LEVEL": "DEBUG",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

ログファイルを確認:

# Windows
type %TEMP%\tree_sitter_analyzer.log

# macOS/Linux
cat /tmp/tree_sitter_analyzer.log

依存関係を確認:

uv run python -c "import tree_sitter_analyzer; print('OK')"

問題: MCPサーバーが頻繁にクラッシュする

症状:

サーバーが予期せず終了する
接続が不安定

解決手順:

メモリ使用量を確認:

# ログでメモリ使用量を監視
export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true
export TREE_SITTER_ANALYZER_FILE_LOG_LEVEL=DEBUG

プロジェクトルートを明示的に設定:

{
  "env": {
    "TREE_SITTER_PROJECT_ROOT": "/absolute/path/to/project"
  }
}

2. ファイル解析の問題

問題: 特定のファイルの解析が失敗する

症状:

"Failed to analyze file" エラー
解析結果が空

解決手順:

ファイルエンコーディングを確認:
```
file -i problematic_file.java
```

デバッグモードで詳細を確認:

export LOG_LEVEL=DEBUG
export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true

uv run tree-sitter-analyzer problematic_file.java --advanced

ファイルサイズを確認:

# 大きすぎるファイルは処理に時間がかかる場合があります
wc -l problematic_file.java

問題: 解析結果が期待と異なる

症状:

要素数が正しくない
構造が正しく認識されない

解決手順:

言語を明示的に指定:

uv run tree-sitter-analyzer file.ext --language java

サポートされている言語を確認:

uv run tree-sitter-analyzer --show-supported-languages

3. ログ設定の問題

問題: ログファイルが作成されない

症状:

TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=trueを設定してもログファイルが作成されない

解決手順:

環境変数の設定を確認:

echo $TREE_SITTER_ANALYZER_ENABLE_FILE_LOG
# "true" が表示されることを確認

ディレクトリの権限を確認:

# カスタムログディレクトリを使用している場合
ls -la /path/to/log/directory

システム一時ディレクトリを確認:

# デフォルトの場所
ls -la /tmp/tree_sitter_analyzer.log  # Linux/macOS
dir %TEMP%\tree_sitter_analyzer.log   # Windows

問題: ログファイルが大きくなりすぎる

症状:

ログファイルがディスク容量を圧迫する

解決手順:

ログレベルを調整:

# DEBUGからINFOに変更
export TREE_SITTER_ANALYZER_FILE_LOG_LEVEL=INFO

定期的なクリーンアップ:

# 古いログファイルを削除
find /tmp -name "tree_sitter_analyzer.log*" -mtime +7 -delete

4. パフォーマンスの問題

問題: 解析が非常に遅い

症状:

大きなファイルの処理に異常に時間がかかる

解決手順:

パフォーマンスログを有効化:

export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true
export TREE_SITTER_ANALYZER_FILE_LOG_LEVEL=DEBUG

処理時間を測定:

time uv run tree-sitter-analyzer large_file.java --advanced

メモリ使用量を監視:

# Linuxの場合
/usr/bin/time -v uv run tree-sitter-analyzer large_file.java --advanced

問題: メモリ不足エラー

症状:

"MemoryError" または "Out of memory" エラー

解決手順:

ファイルを分割して処理:

# 大きなファイルを小さな部分に分けて解析
split -l 1000 large_file.java part_

部分読み取り機能を使用:

uv run tree-sitter-analyzer large_file.java --partial-read --start-line 1 --end-line 500

5. 環境固有の問題

問題: Windows環境でのパス問題

症状:

パスの区切り文字に関するエラー
ファイルが見つからないエラー

解決手順:

絶対パスを使用:

uv run tree-sitter-analyzer C:\full\path\to\file.java

パスをエスケープ:

{
  "env": {
    "TREE_SITTER_PROJECT_ROOT": "C:\\\\path\\\\to\\\\project"
  }
}

問題: macOS/Linux環境での権限問題

症状:

"Permission denied" エラー
ログファイルの作成に失敗

解決手順:

ディレクトリの権限を確認:
```
ls -la /path/to/log/directory
```
適切な権限を設定:
```
chmod 755 /path/to/log/directory
```

🔍 診断ツール

1. 環境診断スクリプト

以下のスクリプトで環境の状態を確認できます：

#!/bin/bash
echo "=== Tree-sitter Analyzer 環境診断 ==="
echo "Python version: $(python --version)"
echo "uv version: $(uv --version)"
echo ""
echo "=== 環境変数 ==="
echo "LOG_LEVEL: $LOG_LEVEL"
echo "TREE_SITTER_ANALYZER_ENABLE_FILE_LOG: $TREE_SITTER_ANALYZER_ENABLE_FILE_LOG"
echo "TREE_SITTER_ANALYZER_LOG_DIR: $TREE_SITTER_ANALYZER_LOG_DIR"
echo "TREE_SITTER_ANALYZER_FILE_LOG_LEVEL: $TREE_SITTER_ANALYZER_FILE_LOG_LEVEL"
echo ""
echo "=== パッケージ確認 ==="
uv run python -c "import tree_sitter_analyzer; print(f'tree-sitter-analyzer: OK')" 2>/dev/null || echo "tree-sitter-analyzer: ERROR"
echo ""
echo "=== ログファイル確認 ==="
if [ -f "/tmp/tree_sitter_analyzer.log" ]; then
    echo "ログファイル: 存在 ($(wc -l < /tmp/tree_sitter_analyzer.log) lines)"
else
    echo "ログファイル: 存在しない"
fi

2. ログ分析ツール

#!/bin/bash
LOG_FILE="${1:-/tmp/tree_sitter_analyzer.log}"

if [ ! -f "$LOG_FILE" ]; then
    echo "ログファイルが見つかりません: $LOG_FILE"
    exit 1
fi

echo "=== ログファイル分析: $LOG_FILE ==="
echo "総行数: $(wc -l < "$LOG_FILE")"
echo "エラー数: $(grep -c "ERROR" "$LOG_FILE")"
echo "警告数: $(grep -c "WARNING" "$LOG_FILE")"
echo ""
echo "=== 最新のエラー ==="
grep "ERROR" "$LOG_FILE" | tail -5
echo ""
echo "=== パフォーマンス情報 ==="
grep "performance" "$LOG_FILE" | tail -5

📞 サポートとヘルプ

問題報告時に含める情報

Issue を作成する際は、以下の情報を含めてください：

環境情報:

python --version
uv --version
uname -a  # Linux/macOS
ver       # Windows

設定情報:
- 使用した環境変数
- MCP設定ファイル（機密情報は除く）
エラー情報:
- 完全なエラーメッセージ
- ログファイルの関連部分
再現手順:
- 実行したコマンド
- 使用したファイル（可能であれば）

よくある質問 (FAQ)

Q: ログファイルはどこに保存されますか？ A: デフォルトではシステムの一時ディレクトリに tree_sitter_analyzer.log として保存されます。TREE_SITTER_ANALYZER_LOG_DIR 環境変数でカスタマイズできます。

Q: ログレベルを変更するにはどうすればよいですか？ A: LOG_LEVEL 環境変数（メインロガー）と TREE_SITTER_ANALYZER_FILE_LOG_LEVEL 環境変数（ファイルログ）で制御できます。

Q: MCPサーバーのデバッグはどのように行いますか？ A: Claude Desktop の設定で環境変数を設定し、ログファイルを確認してください。

Q: 大きなファイルの処理を高速化するにはどうすればよいですか？ A: 部分読み取り機能を使用するか、ファイルを分割して処理することを検討してください。

🔗 関連リソース

デバッグガイド - 詳細なデバッグ手順
README.md - 基本的な使用方法
CONTRIBUTING.md - 開発者向けガイド
GitHub Issues - 問題報告とサポート