KB Guides – Troubleshooting

Common Installation Errors

Below is a curated list of the most frequently encountered installation problems and step‑by‑step solutions. Click on each item to expand the details.

❌ Missing Prerequisite Packages

Ensure the following packages are installed before starting:

  • Python 3.8+ (or the version specified by the docs)
  • Node.js 14+ (if building UI assets)
  • Git 2.20+

On Debian/Ubuntu you can run:

sudo apt-get update && sudo apt-get install python3 git nodejs
❌ Permission Denied (EACCES)

This error usually occurs when installing globally with npm or pip. Avoid using sudo and configure a user‑level directory.

# npm
npm config set prefix "${HOME}/.npm-global"
export PATH="${HOME}/.npm-global/bin:$PATH"

# pip
python3 -m pip install --user package-name
❌ Incompatible Operating System

The installer detects an unsupported OS version. Verify the supported platforms list and upgrade your OS if needed.

For Windows users, make sure you are running the 64‑bit installer on Windows 10 1809 or later.

❌ Network Timeout / Proxy Issues

If you are behind a corporate proxy, configure the proxy settings before running the installer:

# npm
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# git
git config --global http.proxy http://proxy.example.com:8080

Alternatively, set environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
❌ Disk Space Exhausted

Check available space with:

df -h /var /home

Free up space or change the installation directory by passing --install-dir /path/to/dir to the installer script.

Quick Diagnostic Tool