Scanner Ecosystem: CLI, Maven, Gradle, .NET, and Build Integration: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve the exact build/scanner command, stdout/stderr, environment manifest, and source revision.
2. Record server, scanner/plugin, build tool, Java/.NET runtime, and relevant plugin versions.
3. Confirm project/base directory and effective analysis parameters.
4. Inspect whether compilation/test/coverage outputs exist before scan.
5. Inspect scanner indexing/report creation and report-task.txt.
6. If uploaded, follow the exact Compute Engine task.
7. Only after CE success interpret project issues/measures/gate.
8. Change one cause and rerun the smallest equivalent path.

2. Failure ownership matrix

3. Intentionally broken example: remove Java bytecode

In the Maven fixture from Lesson 2, first preserve the known-good build tree. Then deliberately remove compiled classes before invoking analysis in a way that expects Java bytecode.

cd sonar-p07-maven
mvn -B clean verify
find target/classes -type f -print | sort > classes.before.txt
rm -rf target/classes
# Deliberately broken: analysis now lacks the compiled Java context.
mvn -B org.sonarsource.scanner.maven:sonar-maven-plugin:5.7.0.6970:sonar   -Dsonar.host.url="$SONAR_HOST_URL" | tee broken-bytecode.log

Expected diagnostic lesson: the failure/warning belongs to build input, not to the Quality Gate. Preserve broken-bytecode.log, confirm the missing directory, then restore by rebuilding—do not suppress Java files or fabricate an unrelated binaries path.

mvn -B clean verify
mvn -B org.sonarsource.scanner.maven:sonar-maven-plugin:5.7.0.6970:sonar   -Dsonar.host.url="$SONAR_HOST_URL" | tee repaired-bytecode.log

4. .NET lifecycle failure: build outside the envelope

A common conceptual error is to run dotnet build, then later call only the scanner end step or start a new begin/end around no build. The .NET scanner analysis context is not retroactively reconstructed from arbitrary output folders. Preserve the commands and timestamps, then repair by rerunning begin → build → end as one controlled sequence.

5. Wrong working/base directory

Scanner CLI, Maven, Gradle, and .NET do not all infer project base directories identically. Before changing paths, record pwd, repository root, build descriptor locations, sonar.projectBaseDir if set, and indexed-file logs. The .NET scanner changed automatic project-base detection in modern versions, making legacy assumptions particularly dangerous.

6. Scanner/plugin version drift

A pipeline that invokes an unversioned Maven prefix or downloads “latest” CLI can change independently of the server. When a regression appears, preserve the resolved scanner version before retrying. Compare against the server compatibility matrix and the scanner release notes. Roll back only to a supported, previously validated version—not to an arbitrary ancient scanner.

7. Cache problems without evidence destruction

Permissions or corrupted downloads under the scanner user home can fail provisioning. Record SONAR_USER_HOME, ownership, free space, and the failing artifact path. Avoid deleting the entire cache before preserving the failure. A targeted disposable-cache test can isolate cache ownership from project analysis without destroying the original evidence.

8. Security-sensitive troubleshooting boundaries

• Do not switch to an administrator token to bypass permission diagnosis.
• Do not print all environment variables to discover SONAR_TOKEN.
• Do not disable TLS verification as a generic proxy fix.
• Do not delete server database/search state because a local scanner cannot find bytecode.
• Do not lower Quality Gate thresholds to convert a policy result into a scanner “success.”

9. Smallest-equivalent rerun principle

If the failure was missing Maven bytecode, keep the same revision, project key, token scope, server, scanner version, and gate. Rebuild classes and rerun. If the failure was a wrong base directory, change only that path. This causal discipline is what makes the repaired run comparable to the failed run.

Knowledge check

Official references and version notes

• SonarScanner CLI — build-neutral scanner usage, cache behavior, project base directory, and Docker notes.
• SonarScanner CLI 8.1.0.6389 — official release provenance.
• SonarScanner for Maven and release 5.7.0.6970.
• SonarScanner for Gradle and release 7.3.1.8318.
• SonarScanner for .NET usage and release 11.2.1.137242.
• Scanner environment general requirements and JRE auto-provisioning.
• Official scanner examples — recommended scanner choice by build ecosystem.
• Apache Maven downloads — Maven 3.9.16 is the current stable Maven baseline used in the Maven lab.