Static Analysis, Clean Code, Technical Debt, and Quality Governance: Diagnostics, Failure Modes, and Production Practices

1. A red dashboard and a failed analysis are not the same incident

SonarQube sits in a chain of independently failing layers. A scanner can fail before report creation. It can create a report but fail to authenticate or upload. Upload can succeed while asynchronous server processing later fails. Analysis can complete successfully and still produce a red quality gate. CI can then fail because it deliberately enforces that red gate—or fail for an unrelated runner problem.

Troubleshooting starts by naming the failed state precisely. “SonarQube failed” is too vague to be actionable.

2. Evidence-first diagnostic sequence

flowchart TD
A[Preserve first failure] --> B[Confirm versions and edition]
B --> C[Confirm source revision + effective parameters]
C --> D[Inspect indexing/report/upload]
D --> E[Inspect background task]
E --> F[Inspect profile/gate/New Code/security state]
F --> G[Inspect auth/network/CI]
G --> H[Inspect DB/search/JVM/host if relevant]
H --> I[Least destructive correction]
I --> J[Smallest equivalent rerun]

1. Preserve: scanner stdout/stderr, CI log, report-task.txt, server/background-task evidence, current policy identities, and source revision.
2. Version: record Community Build/Server edition and version, scanner/Java/plugin/integration versions.
3. Source/config: prove the exact Git revision, project key, source scope, and effective non-secret parameters.
4. Client lifecycle: distinguish indexing, analysis, report creation, authentication, and upload.
5. Server lifecycle: use the task identity to check queue/processing/terminal state.
6. Policy: only after successful analysis inspect profile, mode, New Code, issues/measures, and gate conditions.
7. External layers: then inspect CI/provider status, auth/TLS/network, or server DB/search/JVM/container state when evidence points there.

3. Symptom-to-layer matrix

4. Intentionally broken lab: fail authentication safely

Reuse the disposable Lesson 2 server/project. Preserve a known-good baseline first. Then remove the analysis token only from the current shell and run the smallest scan:

cp evidence/scanner-baseline.log evidence/known-good-scanner.log
unset SONAR_TOKEN
sonar-scanner 2>&1 | tee evidence/scanner-missing-token.log

Expected diagnostic category: authentication/authorization should fail before a valid new analysis completes. Exact wording is version-sensitive; diagnose from the error, not from a memorized string. Confirm that no new successful task/result appeared for this failed run.

Restore the project-scoped token from your secret source, not from Git or a copied log, and rerun once. The least destructive correction is credential restoration—not an administrator token, TLS disablement, project recreation, or rule changes.

5. Wrong project/revision is a signal-integrity failure

A perfectly successful scan can still be operationally wrong if sonar.projectKey points to another training project or CI checks out a different revision from the one reported in the change request. That is more dangerous than an obvious scanner error because it can produce plausible green evidence for the wrong code.

Before trusting a gate, correlate the Git SHA, CI checkout, scanner analysis revision/project key, task/result, and provider change. If they do not describe the same change, stop the delivery decision. Do not “fix” the mismatch by copying a status from another project.

6. Red gate after successful analysis: policy is working

A red gate is not automatically a defect in SonarQube. It may be the intended outcome: a configured condition detected unacceptable New Code. Inspect the exact failed conditions, measures, New Code boundary, active profile/mode, and source change. Then either remediate the code or follow a documented governance exception process.

7. Blocking legacy code without a New Code strategy

If a mature repository is suddenly gated on every inherited issue, the team may have no feasible path to green. The failure is policy design, not a reason to delete findings. Preserve the overall debt inventory, define a New Code protection strategy, create a separate modernization plan for high-risk legacy areas, and make any gate migration explicit and reviewable.

8. Issue counts changed after a mode switch

Standard Experience and MQR Mode classify rule impacts differently. A count shift after switching modes does not necessarily mean source code changed or analyzers suddenly became better/worse. Compare the same revision and rule/profile state under the documented mode semantics. Update reports, queries, dashboards, and governance language that assumed the old classification.

9. Hotspot versus vulnerability: diagnose the workflow, not the label

If a team files every hotspot as a confirmed vulnerability, triage becomes noisy and security reporting becomes misleading. If it ignores hotspots because they are “not vulnerabilities,” review opportunities are lost. The correct workflow is to inspect the hotspot context, decide whether safeguards make it safe, document that review, and separately remediate actual vulnerability/security issues.

10. Governance failures can look like successful dashboards

• Developer league tables: issue/debt totals become incentives to avoid difficult code, suppress findings, or split work strategically.
• Debt as accounting: a remediation estimate is presented as a budget commitment.
• Average issue closure as productivity: teams optimize ticket churn rather than risk reduction.
• Thresholds chosen after results: the acceptance criterion is no longer independent evidence.

These are not scanner bugs. They are control-design failures and should be repaired through governance, metric interpretation, and review.

11. When to descend into database/search/JVM/container diagnostics

Chapter 01 does not teach production administration, but it must preserve the boundary. Only descend into server infrastructure after evidence shows that source/config, scanner lifecycle, and policy are not the failing layers. Direct edits to the SonarQube database or search index are not normal troubleshooting techniques. Preserve server logs/health data and use supported recovery procedures covered later in the course.

12. Production practices that preserve causal evidence

• Keep scanner, server, language/plugin, and CI integration versions in a run manifest.
• Retain first-failure scanner/CI logs and task IDs before retries.
• Make project/profile/gate/New Code changes auditable.
• Use project-scoped/least-privilege tokens and rotate rather than escalating casually.
• Correlate analysis to immutable revision identity.
• Separate policy exceptions from technical suppressions and give both owners/review dates.
• Rerun the smallest equivalent case after a correction before resuming broad CI traffic.

Knowledge check

Official references and version notes

• SonarQube downloads — release identities for Community Build and SonarQube Server.
• SonarQube Community Build documentation — current self-managed Community Build product documentation.
• Changing modes — Standard Experience versus Multi-Quality Rule (MQR) Mode semantics.
• Quality gate introduction — gate purpose and policy model.
• About new code — Clean-as-You-Code and new-code definition choices.
• Metric definitions — maintainability, remediation effort, debt ratio, and rating definitions.
• Rules — rules, issue generation, and mode-dependent classification.
• SonarScanner CLI — scanner execution guidance.
• SonarSource scanner update-center metadata — scanner release metadata used to pin the lab launcher.
• Official SonarQube Docker tags — container tag provenance for the disposable lab.