トラブルシューティング

esa-cliの使用中に発生する技術的な問題と、その詳細な解決方法を説明します。基本的な問題についてはよくある質問もご確認ください。

📋 目次

エラーコード別解決方法
高度な問題解決
デバッグ情報の取得
サポート

🔧 エラーコード別解決方法

HTTP 401 Unauthorized

症状: 認証エラーが発生する

詳細な解決手順:

現在の設定を確認

cat ~/.esa-cli-config.json

トークンの権限を確認
- esa.ioのアプリケーション設定ページで以下を確認：
  - トークンが有効期限切れになっていないか
  - 適切な権限（read/write）が設定されているか
  - チーム名が正しく設定されているか
新しいトークンを生成
- 既存のトークンを削除
- 新しいトークンを生成（権限はread/write）
- 設定を再実行

esa-cli setup

設定ファイルの権限を確認

ls -la ~/.esa-cli-config.json
chmod 600 ~/.esa-cli-config.json

HTTP 404 Not Found

症状: 記事やリソースが見つからない

詳細な解決手順:

記事の存在確認

# 全記事を検索
esa-cli list --query "記事タイトル"

# 特定のカテゴリで検索
esa-cli list --category "カテゴリ名"

権限の確認
- 記事がプライベート記事でないか
- チームのメンバー権限があるか
- 記事が削除されていないか
URLの確認
- チーム名が正しいか確認
- 記事番号が正しいか確認

HTTP 403 Forbidden

症状: アクセス権限がない

詳細な解決手順:

チームの権限を確認
- esa.ioのWebインターフェースでチームメンバー権限を確認
- 管理者に権限の確認を依頼
記事の権限を確認
- 記事がロックされていないか
- 編集権限があるか

HTTP 429 Too Many Requests

症状: API制限に達した

詳細な解決手順:

リクエスト頻度を確認
- 短時間での大量リクエストを避ける
- バッチ処理の間隔を調整
一時的な回避策

# 処理を一時停止
sleep 60

# 再実行
esa-cli list

処理件数を制限

# 一度に処理する件数を制限
esa-cli list 5

HTTP 500 Internal Server Error

症状: esa.ioのサーバーエラー

詳細な解決手順:

esa.ioのステータスを確認
- esa.io Status でサービス状況を確認
再試行

# 少し待ってから再実行
sleep 30
esa-cli list

キャッシュのクリア

# 一時ファイルを削除
rm -f ~/.esa-cli-cache/*

🔍 高度な問題解決

パフォーマンスの問題

症状: コマンドの実行が異常に遅い

詳細な診断と解決:

ネットワーク診断

# レスポンス時間を測定
curl -w "@-" -o /dev/null -s "https://{your-team}.esa.io" <<'EOF'
     time_namelookup:  %{time_namelookup}\n
        time_connect:  %{time_connect}\n
     time_appconnect:  %{time_appconnect}\n
    time_pretransfer:  %{time_pretransfer}\n
       time_redirect:  %{time_redirect}\n
  time_starttransfer:  %{time_starttransfer}\n
                     ----------\n
          time_total:  %{time_total}\n
EOF

システムリソースの確認

# CPU使用率
top -l 1 | grep "CPU usage"

# メモリ使用率
vm_stat | perl -ne '/page size of (\d+)/ and $size=$1; /Pages free: (\d+)/ and printf "Free: %.1f MB\n", $1 * $size / 1048576'

最適化の実践

# フィルタリングを活用
esa-cli list --category "特定カテゴリ" --user "自分のユーザー名"

# 処理件数を制限
esa-cli list 10

# バックグラウンド処理
nohup esa-cli update-all --category "開発" > update.log 2>&1 &

ファイルシステムの問題

症状: ファイルの読み書きでエラーが発生

詳細な解決手順:

ディスク容量の確認

df -h

ファイル権限の確認

ls -la *.md
chmod 644 *.md

ファイルの整合性確認

# 破損したファイルを検出
find . -name "*.md" -exec file {} \;

# 空のファイルを検出
find . -name "*.md" -size 0

ネットワーク接続の問題

症状: ネットワークエラーが頻繁に発生

詳細な診断:

DNS解決の確認

nslookup {your-team}.esa.io
dig {your-team}.esa.io

プロキシ設定の確認

echo $http_proxy
echo $https_proxy
echo $no_proxy

ファイアウォールの確認

# macOSの場合
sudo pfctl -s rules

VPN接続の影響確認
- VPN接続時にesa.ioへのアクセスが制限されていないか
- 企業ネットワークの制限がないか

設定ファイルの問題

症状: 設定が正しく読み込まれない

詳細な解決手順:

設定ファイルの構文確認

# YAMLの構文チェック
python3 -c "import yaml; yaml.safe_load(open('~/.esa-cli/config.yaml'))"

設定ファイルのバックアップと復元

# バックアップ
cp ~/.esa-cli-config.json ~/.esa-cli-config.json.backup

# 設定をリセット
rm ~/.esa-cli-config.json
esa-cli setup

環境変数の確認

env | grep ESA

🔬 デバッグ情報の取得

問題の詳細な分析には、以下の情報を収集してください：

1. システム情報

# OS情報
uname -a
sw_vers

# Go環境
go version
go env

# シェル情報
echo $SHELL
echo $PATH

2. esa-cli情報

# バージョン情報
esa-cli version

# 設定情報（機密情報は除く）
cat ~/.esa-cli-config.json | jq 'del(.access_token)'

3. ネットワーク情報

# 接続テスト
curl -I https://{your-team}.esa.io

# 詳細な接続情報
curl -v https://{your-team}.esa.io/api/v1/teams

4. ログ情報

# システムログ（macOS）
log show --predicate 'process == "esa-cli"' --last 1h

# アプリケーションログ
find ~/Library/Logs -name "*esa*" -type f

📞 サポート

問題が解決しない場合は、以下の情報とともにGitHub Issuesで報告してください：

必須情報

エラーメッセージの全文
実行したコマンド
esa-cliのバージョン: esa-cli version
OS情報: uname -a
Goバージョン: go version

推奨情報

設定ファイル（アクセストークンは除く）
ネットワーク接続情報
再現手順
期待される動作

報告先

GitHub Issues
タイトルには [Bug] または [Question] を付けてください

📚 関連ドキュメント

よくある質問 - 基本的な問題と解決方法
初期設定と基本操作 - 基本的な使い方
コマンド一覧 - 全コマンドの詳細説明