Troubleshooting
This chapter covers common problems that may occur during the steps in each chapter, organized as symptom → cause → solution. If your symptom is not listed, refer to the official documentation for the relevant tool.
Tool Installation Issues
| Symptom | Cause | Solution |
|---|---|---|
bun command not found | Bun not installed / PATH not set | Review the installation steps in Installing Tools. Close and reopen the terminal. |
java -version does not display a version | JDK not installed / PATH not set | Review the JDK installation steps and JAVA_HOME / PATH settings in Installing Tools. |
mvn --version returns an error | Maven not installed / environment variable misconfiguration | Verify that MAVEN_HOME / JAVA_HOME / PATH are correctly set. |
git --version command not found | Git not installed | Review the installation steps in Installing Tools. |
Installer fails with a permission error (PERMISSION_DENIED) | Insufficient administrator privileges | On Windows, right-click the installer → "Run as administrator". On macOS/Linux, use sudo. |
Download fails (NETWORK_ERROR) | Network issue / behind a proxy | If on a corporate network with a proxy, configure proxy settings for each tool. Consider using offline installers. |
Installation fails (INSTALL_FAILED) | Combined causes such as permissions, network, or conflicts with existing installations | Isolate the issue by checking permissions, network, and existing installations in that order. If a previous installation remains, uninstall it and retry. |
If you are using a proxy on a corporate network, setting the following environment variables will allow most CLI tools to communicate through the proxy:
# bash / zsh example
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
# PowerShell example
$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
Git-specific proxy settings can be configured with git config --global http.proxy http://proxy.example.com:8080.
CLI Execution and Verification Issues
| Symptom | Cause | Solution |
|---|---|---|
bunx @intra-mart/accel init command not found | Bun not installed | Go to the Bun installation steps in Installing Tools. |
bunx @intra-mart/accel init fails to fetch the package | Network or permission issue | See proxy settings in Tool Installation Issues. Retry with administrator privileges. |
bun install fails | Network or permission issue | Recheck proxy settings. Run bun install --verbose to review logs and identify the failure. |
bun run build fails | JAVA_HOME not set / Maven not configured / dependencies not installed | Check tool versions with java -version / mvn --version. Re-run bun install and retry. |
git add returns an error | Git not installed / PATH not set | Check the Git installation steps in Installing Tools. Close and reopen the terminal, then run git --version to verify it works. |
git commit returns an error (message about user.name or user.email) | Git user.name / user.email not configured | Configure with: git config --global user.name "Your Name" and git config --global user.email "your.email@example.com". Then run git commit again. |
| Cannot sign in to the agent extension | Account not subscribed / browser authentication callback failed | Verify the account subscription status. Disable the browser's popup blocker and retry. |
Conflicts Reported After Running accel update
If files you have edited overlap with template updates, conflict markers in the same format as git (<<<<<<< / ======= / >>>>>>>) are inserted at the affected locations. This is not an abnormal termination. Check the list of files shown at the end, and resolve the marked sections in each file manually. After resolving, run bun install and bun run build to confirm the build passes (install / build are not run automatically when conflicts occur).