Installation Issues

Troubleshooting problems during Bob the Fixer installation.

Port Conflicts

Symptoms

Port 9000 (SonarQube Web UI) already in use!
Process: gvproxy
PID: 12345

Diagnosis

Check what's using port 9000:

# macOS
lsof -i :9000

# Linux
netstat -tuln | grep 9000
# or
ss -tuln | grep 9000

Solutions

Option 1: Stop the Conflicting Process

# If it's a container
docker stop <container_id>

# If it's a regular process
sudo kill -15 <PID>

Note: Some processes like gvproxy (used by Podman) cannot be killed directly. See Protected Processes below.

Option 2: Use Alternative Port

During installation, choose option 2 when prompted to use port 9001 instead.

Or manually edit the compose file:

# Edit infrastructure/podman-compose.yml
# Change: "9000:9000" to "9001:9000"

Then update your SONAR_URL:

export SONAR_URL="http://localhost:9001"

Option 3: Restart Container Runtime

If gvproxy or docker-proxy is blocking:

# For Docker Desktop
# Quit Docker Desktop from menu bar, then restart

# For Podman
podman machine stop
podman machine start

Protected Processes

These system processes cannot be terminated manually:

Process	Used By	Solution
gvproxy	Podman	Restart Podman
docker-proxy	Docker	Restart Docker
containerd	Docker	Restart Docker
dockerd	Docker	Restart Docker

SonarQube Not Starting

Symptoms

docker ps
# Shows: bobthefixer_sonarqube - Exited (1)

Diagnosis

# Check logs
docker logs bobthefixer_sonarqube

# Common errors:
# - "max virtual memory areas vm.max_map_count is too low"
# - "Can not connect to database"
# - "Out of memory"

Solutions

Memory Issue (Linux)

# Increase vm.max_map_count
sudo sysctl -w vm.max_map_count=262144

# Make permanent
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

Database Connection Failed

# Check PostgreSQL is running
docker ps | grep postgres

# If not running, start it first
docker start bobthefixer_postgres

# Wait for it to be ready
sleep 10

# Then start SonarQube
docker start bobthefixer_sonarqube

Out of Memory

Increase Docker/Podman memory allocation:

Docker Desktop:

1. Open Docker Desktop
2. Settings → Resources
3. Increase Memory to 4GB+
4. Apply & Restart

Podman:

podman machine stop
podman machine set --memory 4096
podman machine start

Build Failures

Symptoms

npm error code 1
npm error path /path/to/bob-the-fixer

Solutions

Clear and Rebuild

# Remove node_modules and build artifacts
rm -rf node_modules
rm -rf packages/core/dist
rm -rf packages/core/node_modules

# Fresh install
npm install

# Rebuild
npm run build

Node Version Issues

# Check Node version
node --version

# Bob the Fixer requires Node 18+
# If using nvm:
nvm install 18
nvm use 18

Permission Errors (Linux)

# If npm install fails with EACCES
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /path/to/bob-the-fixer

# Or use sudo for global installs
sudo npm install -g @anthropic-ai/claude-code

Docker/Podman Not Found

Symptoms

No container runtime found!
Bob the Fixer requires Docker or Podman.

Solutions

Install Docker (macOS)

1. Download Docker Desktop
2. Install and launch
3. Wait for Docker to start
4. Re-run installation

Install Docker (Linux)

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in

# Verify
docker --version

Install Podman (Linux)

# Ubuntu 22.04+
sudo apt install podman podman-compose

# Fedora
sudo dnf install podman podman-compose

# Verify
podman --version

AI CLI Not Detected

Symptoms

No AI CLI detected!
Bob the Fixer is an MCP server that requires at least one compatible AI CLI.

Solutions

Install at least one supported AI CLI:

# Claude Code (recommended)
npm install -g @anthropic-ai/claude-code
claude auth login

# Google Gemini
npm install -g @google/gemini-cli
gemini auth login

# OpenAI Codex
npm install -g @openai/codex
codex auth login

# GitHub Copilot
npm install -g @github/copilot

Then re-run the installer.

Rollback and Recovery

Automatic Rollback

If installation fails, you'll be prompted:

What do you want to do?
  1) Full rollback (remove everything)
  2) Partial cleanup (keep data)
  3) Nothing (analyze manually)

Manual Rollback

cd /path/to/bob-the-fixer

# Source rollback utilities
source lib/rollback.sh

# Full rollback
perform_full_rollback

# Or partial cleanup (keeps data)
perform_partial_cleanup

What Gets Removed

Rollback Type	Containers	Volumes	Config	Build
Full	✅	✅	✅	✅
Partial	✅ (stopped)	❌	✅	❌

Start Fresh

After rollback:

./install.sh

Installation Logs

Log Locations

Log	Location
Install log	/tmp/bob-install-YYYYMMDD_HHMMSS.log
Rollback log	/tmp/bob-installer-rollback.log
State file	/tmp/bob-installer-state.txt

Enable Verbose Logging

# Run installer with debug output
DEBUG=1 ./install.sh 2>&1 | tee install-debug.log

Common Installation Errors

Error	Cause	Fix
EACCES	Permission denied	Fix npm permissions or use sudo
ENOENT	File not found	Check paths, run from correct directory
ETIMEDOUT	Network timeout	Check internet connection
ENOSPC	Disk full	Free up disk space
ENOMEM	Out of memory	Increase Docker memory

Next Steps

After resolving installation issues:

1. Verify installation:

   docker ps | grep bob
   curl http://localhost:9000/api/system/status

2. Continue with Quick Start

3. If problems persist, see Connection Issues