Troubleshooting

ELI5 Explanation

This lesson is a cheat sheet for when things go wrong: scan won't run, gate keeps failing, pipeline results don't match the UI, or nothing shows up at all.

Common Problem Categories

SonarQube problems fall into four categories: authentication & connectivity, scan failures, quality gate mis-configuration, and integration issues. Each has a distinct diagnosis path.

Issue: Scan Fails With Authentication Error

# Test the token manually
curl -u $SONAR_TOKEN: http://localhost:9000/api/authentication/validate
# Expected: {"valid":true}
# If false: token is expired, revoked, or the variable is empty

# Check the token has "Execute Analysis" permission in SonarQube
# Admin → Security → Global Permissions → Execute Analysis

Issue: Scan Runs But No Project Appears

# Confirm the task completed on the server
curl -u $SONAR_TOKEN: \
  "http://localhost:9000/api/ce/activity?component=my-app&ps=5"

# If task is in FAILED state, get the task ID and check logs
curl -u $SONAR_TOKEN: \
  "http://localhost:9000/api/ce/task?id="

# Check server logs for the scanner analysis log
grep "ERROR" /opt/sonarqube/logs/ce.log | tail -20

Issue: Coverage Shows 0% Despite Tests Passing

# Confirm coverage report exists before scan
find . -name "jacoco.xml" 2>/dev/null
find . -name "lcov.info" 2>/dev/null

# Add correct path in sonar-project.properties
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

# For JS/TS (Jest)
sonar.javascript.lcov.reportPaths=coverage/lcov.info

# Re-run scan and verify coverage node appears in analysis logs

Issue: Quality Gate Always Fails on New Code

# Get full gate status with failed conditions
curl -u $SONAR_TOKEN: \
  "http://localhost:9000/api/qualitygates/project_status?projectKey=my-app" \
  | python3 -m json.tool

# Conditions with status FAILED show the metric, operator, threshold, and actual value
# Example: coverage < 80 (actual: 62.3)

# Check which lines are counted as new code
# Project settings → New Code → change period if needed

Issue: Pipeline Fails But SonarQube UI Shows PASSED

Root cause: the pipeline step is checking the wrong project key, or the quality gate check step is running before the SonarQube server has finished analysis (async). Increase the timeout on the quality gate check step and confirm SONAR_HOST_URL and project key match exactly.

Issue: PR Decoration Not Appearing

# Required parameters for PR decoration
sonar-scanner \
  -Dsonar.pullrequest.key=$PR_NUMBER \
  -Dsonar.pullrequest.branch=$HEAD_BRANCH \
  -Dsonar.pullrequest.base=$BASE_BRANCH \
  -Dsonar.pullrequest.provider=github

# Also verify ALM integration is configured in:
# Admin → DevOps Platform Integrations

Diagnostic Checklist

• Token is valid and has Execute Analysis permission
• sonar.projectKey matches the key in SonarQube UI
• fetch-depth: 0 is set in checkout
• Coverage report path is correct and the file exists
• Quality gate is correctly assigned to the project
• New code period is configured (default: previous version)
• CE task completed successfully (check api/ce/activity)
• Firewall/proxy allows scanner to reach SonarQube server

Interview Questions

Real-world Use Case

A platform team created a shared troubleshooting runbook in Confluence mapping each error pattern to a root cause and fix. Onboarding time for new teams dropped from 3 days to half a day.

Summary

Systematic diagnosis using the SonarQube API, logs, and a structured checklist resolves most operational issues quickly. The final lesson prepares you for interview questions across all SonarQube topics.