Troubleshooting Overview

Quick reference for resolving common Bob the Fixer issues.

Issue Categories

Category	Common Symptoms	Quick Link
Installation	Port conflicts, build failures, permission errors	Installation Issues
Connection	401/403 errors, timeouts, connection refused	Connection Issues
Scanning	Sources not found, slow scans, no issues detected	Scanning Issues
AI Integration	Tools not available, MCP errors, slow responses	AI Integration Issues

Quick Diagnostics

Check Installation Status

# Verify SonarQube is running
docker ps | grep sonar

# Check container health
docker logs bobthefixer_sonarqube --tail 50

# Verify MCP server exists
ls -la /path/to/bob-the-fixer/packages/core/dist/universal-mcp-server.js

Check Configuration

# View local config
cat bobthefixer.env

# Validate configuration
# In your AI assistant:
sonar_config_manager action="validate"

Check Connectivity

# Test SonarQube API
curl http://localhost:9000/api/system/status

# Test authentication
curl -u "your-token:" http://localhost:9000/api/authentication/validate

Run Full Diagnostics

In your AI assistant:

Diagnose my SonarQube connection and permissions

This runs sonar_diagnose_permissions which checks:

• Server connectivity
• Token validity
• Required permissions
• Project access

Common Quick Fixes

SonarQube Not Running

# Start containers
cd /path/to/bob-the-fixer
docker-compose -f infrastructure/podman-compose.yml up -d

# Wait for startup (takes 1-2 minutes)
sleep 60

# Verify
curl http://localhost:9000/api/system/status

Port 9000 Already in Use

# Find what's using it
lsof -i :9000

# Option 1: Stop the conflicting service
# Option 2: Use alternative port 9001 (edit podman-compose.yml)

Token Invalid or Expired

1. Go to SonarQube UI: http://localhost:9000
2. Login as admin
3. Navigate to My Account → Security
4. Generate new token
5. Update your AI CLI configuration

MCP Server Not Found

# For Claude
claude mcp list

# Re-register if missing
claude mcp add bob-the-fixer node "/path/to/universal-mcp-server.js" \
  --scope user \
  --env SONAR_URL=http://localhost:9000 \
  --env SONAR_TOKEN="your-token"

Error Code Reference

Error	Meaning	Solution
401 Unauthorized	Invalid or missing token	Generate new token
403 Forbidden	Token lacks permissions	Check permissions
Connection refused	SonarQube not running	Start containers
ECONNREFUSED	Network/port issue	Check port
Sources not found	Wrong source paths	Configure sources
No issues found	Missing plugins/rules	Check configuration

Log Locations

Component	Log Location
SonarQube	docker logs bobthefixer_sonarqube
PostgreSQL	docker logs bobthefixer_postgres
MCP Server	/tmp/bobthefixer-mcp.log (if configured)
Installation	/tmp/bob-install-*.log
Rollback	/tmp/bob-installer-rollback.log

Getting Help

If you're still stuck after checking this documentation:

1. Enable debug logging:

   export LOG_LEVEL=debug

2. Collect diagnostic information:

   # In your AI assistant
   sonar_diagnose_permissions verbose=true

3. Check GitHub Issues: github.com/andrearaponi/bob-the-fixer/issues

4. Open a new issue with:

   • Error messages
   • Log output
   • Your configuration (redact tokens)
   • Steps to reproduce

Recovery Options

If installation is corrupted, you have several recovery options:

Partial Cleanup (Keep Data)

cd /path/to/bob-the-fixer
source lib/rollback.sh
perform_partial_cleanup

This stops containers but preserves your data.

Full Rollback

cd /path/to/bob-the-fixer
source lib/rollback.sh
perform_full_rollback

This removes everything and lets you start fresh.

Re-run Installation

cd /path/to/bob-the-fixer
./install.sh

The installer will detect existing components and offer to reconfigure.