Skip to main content

Connection Issues

Troubleshooting SonarQube connectivity and authentication problems.

401 Unauthorized​

Symptoms​

Error: 401 Unauthorized
Message: "Not authorized. Analyzing this project requires authentication."

Causes​

  • Token is invalid
  • Token has expired
  • Token is missing
  • Wrong token format

Diagnosis​

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

# Should return:
# {"valid":true}

# If invalid:
# {"valid":false}

Or use the diagnostic tool:

# In your AI assistant
Diagnose my SonarQube connection

Solutions​

Generate New Token​

  1. Open SonarQube UI: http://localhost:9000
  2. Login (default: admin/admin)
  3. Click your avatar → My Account
  4. Go to Security tab
  5. Under "Generate Tokens":
    • Name: bob-the-fixer
    • Type: Project Analysis Token or Global Analysis Token
  6. Click Generate
  7. Copy the token (shown only once!)

Update Token in Configuration​

For Claude:

claude mcp remove bob-the-fixer
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-new-token"

For GitHub Copilot: Edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "bob-the-fixer": {
      "env": {
        "SONAR_TOKEN": "your-new-token"
      }
    }
  }
}

Reset Local Config​

# In your AI assistant
Reset my SonarQube configuration

Then run sonar_auto_setup to create a new configuration.

403 Forbidden​

Symptoms​

Error: 403 Forbidden
Message: "Insufficient privileges"

Causes​

  • Token lacks required permissions
  • Token is for a different project
  • Project permissions not granted

Diagnosis​

# In your AI assistant
Check my token permissions

This runs sonar_diagnose_permissions which shows:

PERMISSIONS:

  Project: myproject-a1b2c3d4

  ┌────────────────────────┬────────┬───────────┐
  │ Permission             │ Status │ Required  │
  ├────────────────────────┼────────┼───────────┤
  │ Browse                 │ ✅     │ Yes       │
  │ Execute Analysis       │ ❌     │ Yes       │
  │ See Source Code        │ ✅     │ No        │
  └────────────────────────┴────────┴───────────┘

Solutions​

Use Global Analysis Token​

Generate a Global Analysis Token instead of Project token:

  1. My Account → Security
  2. Generate Token → Type: Global Analysis Token
  3. Update your configuration

Grant Project Permissions​

In SonarQube UI:

  1. Go to your project
  2. Project Settings → Permissions
  3. Add user/token with:
    • "Browse"
    • "Execute Analysis"

Check Token Type​

Token TypeCan Do
User TokenAll projects user has access to
Global AnalysisAll projects (analysis only)
Project AnalysisSingle project only

Connection Refused​

Symptoms​

Error: ECONNREFUSED
Message: "connect ECONNREFUSED 127.0.0.1:9000"

Causes​

  • SonarQube not running
  • Wrong URL/port
  • Firewall blocking
  • Network issues

Diagnosis​

# Check if SonarQube is running
docker ps | grep sonar

# Check container status
docker ps -a | grep bobthefixer

# Test connectivity
curl http://localhost:9000/api/system/status

Solutions​

Start SonarQube​

cd /path/to/bob-the-fixer

# Start containers
docker-compose -f infrastructure/podman-compose.yml up -d

# Wait for startup
echo "Waiting for SonarQube..."
until curl -s http://localhost:9000/api/system/status | grep -q '"status":"UP"'; do
  sleep 5
done
echo "SonarQube is ready!"

Check Container Logs​

# SonarQube logs
docker logs bobthefixer_sonarqube --tail 100

# Look for:
# - "SonarQube is operational"
# - Error messages

Verify URL Configuration​

# Check what URL is configured
echo $SONAR_URL

# Common mistakes:
# - Using https:// instead of http://
# - Wrong port (9001 instead of 9000)
# - Missing http:// prefix

Timeout Errors​

Symptoms​

Error: ETIMEDOUT
Error: Request timeout

Causes​

  • SonarQube still starting
  • Server overloaded
  • Network latency
  • Large project taking too long

Solutions​

Wait for Startup​

SonarQube can take 1-2 minutes to start:

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

# Response during startup:
# {"status":"STARTING"}

# When ready:
# {"status":"UP"}

Increase Timeouts​

For OpenAI Codex (most prone to timeouts):

codex mcp add bob-the-fixer \
  --env MCP_REQUEST_TIMEOUT=600000 \
  --env SCAN_TIMEOUT=1200000 \
  -- node "/path/to/universal-mcp-server.js"

Check Server Resources​

# Check Docker resource usage
docker stats bobthefixer_sonarqube

# If memory/CPU maxed out, increase Docker resources

DNS/Hostname Issues​

Symptoms​

Error: getaddrinfo ENOTFOUND sonarqube
Error: Could not resolve hostname

Causes​

  • Using container hostname instead of localhost
  • DNS not configured
  • Network isolation

Solutions​

Use Correct URL​

Always use localhost or 127.0.0.1, not container names:

# Correct
SONAR_URL=http://localhost:9000

# Wrong (won't work from host)
SONAR_URL=http://sonarqube:9000

Check /etc/hosts​

cat /etc/hosts | grep localhost
# Should include:
# 127.0.0.1 localhost

SSL/TLS Issues​

Symptoms​

Error: unable to verify the first certificate
Error: self signed certificate

Causes​

  • Using HTTPS with self-signed certificate
  • Certificate chain incomplete

Solutions​

Use HTTP for Local​

For local development, use HTTP:

SONAR_URL=http://localhost:9000

Configure Certificate (Production)​

For production with HTTPS:

# Add CA certificate
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Verifying Connection​

Complete Connection Test​

#!/bin/bash
# test-connection.sh

SONAR_URL="${SONAR_URL:-http://localhost:9000}"
SONAR_TOKEN="${SONAR_TOKEN:-your-token}"

echo "Testing SonarQube connection..."

# Test 1: Server reachable
echo -n "1. Server reachable: "
if curl -s "$SONAR_URL/api/system/status" | grep -q "UP"; then
  echo "✅ PASS"
else
  echo "❌ FAIL - Server not running"
  exit 1
fi

# Test 2: Token valid
echo -n "2. Token valid: "
if curl -s -u "$SONAR_TOKEN:" "$SONAR_URL/api/authentication/validate" | grep -q "true"; then
  echo "✅ PASS"
else
  echo "❌ FAIL - Invalid token"
  exit 1
fi

# Test 3: API accessible
echo -n "3. API accessible: "
if curl -s -u "$SONAR_TOKEN:" "$SONAR_URL/api/projects/search" | grep -q "components"; then
  echo "✅ PASS"
else
  echo "❌ FAIL - API error"
  exit 1
fi

echo ""
echo "All connection tests passed!"

Using Built-in Diagnostics​

# In your AI assistant
Run full diagnostics on my SonarQube setup

This provides comprehensive status including:

  • Server connectivity
  • Token validation
  • Permission checks
  • Project status

Next Steps​

If connection issues persist:

  1. Check Installation Issues for setup problems
  2. Verify your Configuration
  3. See AI Integration Issues for MCP problems