メインコンテンツまでスキップ

トラブルシューティング

各章の作業中に発生しうる代表的な問題への対応を、症状 → 原因 → 解決策 の形式で整理します。該当する症状が一覧にない場合は、各ツールの公式ドキュメントもご参照ください。

ツールインストール関連​

症状原因解決策
bun コマンドが見つからないBun 未インストール／PATH 未設定ツールのインストール のインストール手順を再確認。ターミナルを一度閉じて開き直す。
java -version でバージョンが表示されないJDK 未インストール／PATH 未設定ツールのインストール の JDK インストール手順と JAVA_HOME / PATH 設定を再確認。
mvn --version でエラーMaven 未インストール／環境変数設定不備MAVEN_HOME / JAVA_HOME / PATH が正しく設定されているか確認。
git --version でコマンドが見つからないGit 未インストールツールのインストール のインストール手順を再確認。
インストーラが権限エラーで進まない（PERMISSION_DENIED）管理者権限不足Windows はインストーラを右クリック →「管理者として実行」。macOS/Linux は sudo を利用。
ツールのダウンロードが失敗する（NETWORK_ERROR）ネットワーク障害／プロキシ配下社内プロキシを利用している場合は、各ツールのプロキシ設定を行う。オフラインインストーラの利用も検討する。
ツールのインストールに失敗する（INSTALL_FAILED）権限・ネットワーク・既存インストールの競合など複合要因上記 3 点（権限／ネットワーク／既存インストール）を順番に切り分け。既存インストールが残っている場合はアンインストール後に再試行。
プロキシ設定の基本

企業ネットワークでプロキシを利用している場合、次の環境変数を設定することで多くの CLI ツールがプロキシ経由で通信できるようになります。

# bash / zsh の例
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
# PowerShell の例
$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"

Git 固有のプロキシ設定は git config --global http.proxy http://proxy.example.com:8080 で行えます。

CLI 実行・動作確認関連​

症状原因解決策
bunx @intra-mart/accel init でコマンドが見つからないBun 未インストールツールのインストール の Bun インストール手順へ。
bunx @intra-mart/accel init でパッケージ取得に失敗ネットワークまたは権限の問題ツールインストール関連 のプロキシ設定を参照。管理者権限で再試行。
bun install が失敗するネットワークまたは権限の問題プロキシ設定を再確認。bun install --verbose でログを確認し、失敗箇所を特定。
bun run build が失敗するJAVA_HOME 未設定／Maven 未設定／依存関係未インストールjava -version / mvn --version でツールのバージョン確認。bun install を再実行してから再試行。
git add でエラーが表示されるGit 未インストール／PATH 未設定ツールのインストール の Git インストール手順を確認。ターミナルを閉じて開き直し、git --version で動作確認。
git commit でエラーが表示される（user.name や user.email に関するメッセージ）Git の user.name / user.email が未設定次のコマンドで設定：git config --global user.name "Your Name" と git config --global user.email "your.email@example.com"。その後、再度 git commit を実行。
エージェント拡張機能でサインインできないアカウント未契約／ブラウザ認証の戻りが失敗アカウントの契約状況を確認。ブラウザのポップアップブロックを解除して再試行。

accel update 実行後にコンフリクトが表示された​

ユーザーが編集したファイルとテンプレートの更新が重なった場合、該当箇所に git と同じ形式のコンフリクトマーカー（<<<<<<< / ======= / >>>>>>>）が挿入されます。これは異常終了ではありません。終了時に表示されるファイル一覧を確認し、各ファイルのマーカー部分を手動で解決してください。解決後に bun install と bun run build を実行して、ビルドが通ることを確認します（コンフリクト発生時は install / build が自動実行されないため）。