SonarQube Product Model, Editions, Components, and Architecture: Diagnostics, Failure Modes, and Production Practices

1. “SonarQube failed” is not a diagnosis

A missing scanner executable is a client/runtime problem. HTTP 401/403 during upload is authentication/authorization. An accepted report with a failed Compute Engine task is server processing. A completed analysis with a red gate is policy outcome. A green server result with missing PR decoration is usually an external integration/provider problem.

2. Evidence-first sequence

1. Preserve scanner output, task metadata, CE response/logs, CI log, provider status, API responses.
2. Confirm exact product/edition/version plus scanner/runtime/plugin/database/integration versions relevant to the symptom.
3. Confirm revision, project key, effective parameters, and token/permission scope.
4. Prove report creation/upload and task identity.
5. Prove CE state and first failure.
6. Prove project/profile/New Code/gate result.
7. Prove CI/provider/PR integration state.
8. Inspect database/search/JVM/host/container only if prior evidence points there.
9. Correct narrowly and rerun the smallest equivalent case.

3. Broken example: upload success mistaken for analysis success

scanner: report uploaded
ceTaskId=AX-example-123
server task: FAILED
analysis result: not completed

The client succeeded in upload, but the analysis did not complete. Preserve the task/error and repair the server-side cause. Re-run the same revision/inputs; do not change project key to make a new green history.

4. Broken example: edition assumption

A team copies a commercial branch/PR setup into Community Build and blames the scanner. First prove product identity and current feature matrix. If the capability is commercial, evaluate the appropriate licensed edition, redesign around Community capabilities, or simulate it for training. Do not install unverified plugins or spoof license state.

5. Broken example: IDE treated as authoritative

The IDE shows no findings while CI/server gate is red. Compare revision, scope, connected configuration, imported reports, and server policy. The IDE can legitimately have a different local context. Do not lower the server gate to match a workstation.

6. Broken example: Cloud and Server configuration mixed

A migration attempts to carry a self-managed sonar.properties infrastructure setting into SonarQube Cloud. Reclassify each setting: project/organization/integration behavior may have a Cloud equivalent; self-managed process/database/search settings do not belong to the hosted infrastructure plane.

7. Failure-layer table

8. Database/search production boundary

Never directly edit SonarQube database rows or search documents as a troubleshooting shortcut. Preserve logs/health evidence and follow current supported backup/recovery/update guidance. Likewise, do not delete logs or caches before capturing first failure.

9. Security-sensitive diagnostics

• Least-privilege tokens; redact secrets.
• No TLS-verification disablement as a connectivity shortcut.
• No public exposure of database/search/cluster ports.
• No identity bypass to “prove” integration.
• No unsupported downgrade or incompatible restore.
• No broad project deletion or mass suppression to make CI green.

10. Production incident packet

Attach the redacted architecture manifest, effective parameters, scanner log, task identity, CE status/error, relevant server log, policy evidence, provider/CI status, and the exact correction.

Knowledge check

Official references and version notes

• SonarQube downloads and edition comparison — current Community Build, Developer, Enterprise, Data Center, and LTA identities.
• Community Build documentation — free self-managed baseline.
• SonarQube Server documentation — commercial Server behavior, operations, analysis, and integrations.
• SonarQube for IDE documentation — local analysis and connected mode.
• SonarQube Cloud documentation — hosted-product boundary.
• Release announcements — dated release cross-checks.