Projects, Tokens, Scanners, Analysis Parameters, and First Analysis: Diagnostics, Failure Modes, and Production Practices

1. A red job is only a symptom

2. Evidence-first diagnostic sequence

1. Preserve scanner output and report-task.txt if it exists.
2. Record SonarQube edition/version and scanner/JRE/plugin/integration versions involved.
3. Record exact Git revision and dirty state.
4. Reconstruct effective project key, host URL, base directory, source scope, and overrides.
5. If upload occurred, follow the exact ceTaskId.
6. Only after CE success inspect gate/profile/New Code/issues/measures.
7. If CE fails, inspect database/search/JVM/host/container/plugin evidence.
8. Change one suspected cause and rerun the same source/configuration otherwise.

3. Intentionally broken example: wrong command-line key

The project file has the correct key and the token is scoped to it. Run this only against the disposable lab:

sonar-scanner -Dsonar.host.url="$SONAR_HOST_URL"   -Dsonar.projectKey=academy-sonarqube-p06-other

The command-line key overrides the file. The scoped token should not gain authority over another project. The exact error depends on project existence and permissions, so preserve it. Do not “fix” this by switching to an administrator token.

4. Repair the cause, not the permission model

1. Confirm the repository file says academy-sonarqube-p06.
2. Identify the higher-precedence -Dsonar.projectKey.
3. Remove only that override.
4. Rerun at the same Git revision with the same project token.
5. Compare project identity, indexing, report/task evidence, and outcome.

5. Keep five statuses separate

• Scanner process success — client execution completed.
• Report upload — server accepted report and created CE work.
• CE task success — server processed/persisted analysis.
• Quality Gate pass — completed analysis satisfies policy.
• CI job pass — pipeline logic decided to pass; it may or may not wait for gate.

A gate failure is not a scanner defect. A scanner failure before upload is not a quality-policy failure.

6. Wrong base directory / indexed-file set

If the scanner starts from the wrong directory, relative configuration and sources can resolve incorrectly. Diagnose from the scanner-reported base directory and indexing evidence. Do not compensate with broad inclusions until you understand why the base/scope is wrong. Chapter 08 expands this into full indexing/SCM diagnostics.

7. Token failures without escalation

Inspect token type, associated project, author Execute Analysis permission, expiration/revocation, and target server. Never commit the token, disable authentication, log it for debugging, edit permission rows directly in the database, or use an admin token merely to make the error disappear.

8. CE/server failure

If upload produced a task ID and the task fails, preserve that task and inspect Background Tasks / ce.log. Database outages, search failures, incompatible plugins, malformed reports, or resource pressure belong to server-side diagnosis. Direct database/search edits are unsupported shortcuts and can damage consistency.

9. Evidence-destroying shortcuts

10. Failure-analysis lab

1. Run the deliberate wrong-key command.
2. Record whether failure occurs before or after report upload.
3. Classify the failing layer before changing anything.
4. Remove only the project-key override.
5. Rerun at the same revision and compare evidence.
6. Revoke the disposable token after completing the exercise.

Knowledge check

Official references and version notes

• SonarQube downloads — current Community Build and Server release identities.
• Managing your tokens — user, project-analysis, and global-analysis token semantics.
• Analysis-parameter configuration overview — precedence and persistence.
• Managing JRE auto-provisioning and scanner environment requirements.
• SonarScanner CLI 8.1.0.6389 and official scanner metadata.
• Web API — bearer authentication and the gradual Web API V2 transition.
• CI integration overview — asynchronous processing and quality-gate waiting.