トラブルシューティング

このページはよくある問題とその対処法をまとめています。問題が解決しない場合は、エラーメッセージを元にさらに調査してください。

認証エラー（401 / トークン関連）

WARNING

MOTION_TOKEN または --token が未設定の場合、CLI は実行を中断します。

• 対処:
  • 環境変数 MOTION_TOKEN が正しく設定されているか確認します。
  • CI 環境ではシークレットに登録されているか確認してください（例: GitHub Secrets）。
  • トークンが期限切れでないか、アクセス権が正しいかを確認します。

ネットワーク / プロキシ関連の失敗

• 症状: ダウンロードで ECONNREFUSED やタイムアウト、SSL エラーが出る。
• 対処:
  • 環境変数 HTTP_PROXY / HTTPS_PROXY を設定するか、--proxy <url> を指定してください。
  • 社内プロキシ環境ではプロキシの認証や証明書の設定を確認してください。

ダウンロード失敗（再試行）

• CLI は --retry（デフォルト 2）で再試行します。ネットワークが不安定な場合は増やしてください。

npx motion-plus-installer --retry 5

require is not defined や ESM/CJS のエラー

• 症状: Node 実行時に ESM/CJS の互換エラーが出る。
• 対処:
  • 配布版はビルド済みの CommonJS を想定しています。リポジトリのソースを直接実行する場合は pnpm run build を行ってから試してください。

パッケージマネージャ検出の問題（自動検出が期待通りに動かない）

• 症状: --pm-cmd を指定していないのに意図しないマネージャが使われる。
• 対処:
  • CI では明示的に --pm-cmd pnpm（あるいは npm）を指定してください。詳細は パッケージマネージャ検出 を参照してください。
  • ローカルでは package.json#packageManager フィールドやロックファイル（pnpm-lock.yaml, package-lock.json, yarn.lock）の存在で検出されます。必要に応じてロックファイルを確認してください（関連: パッケージマネージャ検出／CLI リファレンス）。

権限エラー（ファイルシステム）

• 症状: 出力先に書き込めない、EPERM、EACCES エラー。
• 対処:
  • --out を使用して書き込み可能なパスを指定するか、node_modules 配下の書き込み権限を確認してください。
  • グローバルインストール・グローバル実行では管理者権限が必要になる場合があります。

それでも解決しない場合

• エラーメッセージと実行コマンド（トークンは含めない）を添えて issue を作成してください。