Release Cycle, LTA Strategy, Upgrade Paths, and Migration Planning: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve scanner logs, target web/CE/ES/system logs, CI/API evidence, backup ID/checksum and migration timestamps.
2. Confirm exact source/target SonarQube versions, edition/release stream, Java/runtime, database, scanner and plugin versions.
3. Confirm the documented update path and every required intermediate LTA/year bridge.
4. Confirm the source revision/effective scanner parameters and preserve report-task.txt/ceTaskId when upload occurred.
5. Inspect migration/startup state before project policy.
6. Then inspect profiles, gates, New Code, security/analyzer differences, API/CI/IDE/provider integrations.
7. Inspect database/search/JVM/host/container resources only when evidence points there.
8. Apply the least destructive supported correction and rerun the smallest equivalent rehearsal.

2. Failure: jumping an unsupported path

Broken plan: Community Build 25.9 → 26.9 directly. The current path rule says cross-year updates require the documented year bridge; 2025→2026 has special December/January guidance. The correct response is to stop in preflight and use the current calculator/rule, not “try it and see.”

evidence/broken/path-preflight.txt
BLOCKED: proposed path crosses Community Build calendar year without required bridge release.
source=25.9.0.112764
target=26.9.0.129388
action=consult current update-path calculator/rules; add required bridge hop(s)

3. Failure: treating database migration as downgrade-safe

Once the target has migrated the schema, do not start the old server against that database. A “binary rollback” without database rollback is not the documented recovery model. Preserve the target failure evidence, stop the target, restore the pre-update DB backup into the rollback database, switch to the old server, then start it.

4. Failure: incompatible third-party plugin blocks startup

A common startup failure is carrying forward a JAR whose plugin API range no longer matches the target. The evidence belongs in target startup logs and the plugin inventory. Repair by removing or replacing the incompatible plugin in the target deployment, using the current plugin version matrix and preserved provenance; do not copy the entire old plugins directory or downgrade the server reflexively.

symptom: target startup fails while database is reachable
first evidence: target web/sonar startup log + exact plugin JAR checksum
owning layer: plugin compatibility / server extension
least-destructive repair: remove/update only incompatible target plugin
rerun: same target version + same rehearsal DB/restore point as appropriate

5. Failure: production is the first migration rehearsal

If the only backup has never been restored and no staging clone has run the target migration, your maintenance window is performing discovery under outage pressure. Chapter 28's restore drill is a prerequisite: use a recent backup to create a production-like rehearsal database, migrate it, capture duration and disk growth, and run the acceptance suite before scheduling production.

6. Failure: changing server, database, OS and CI simultaneously

If an upgrade also changes PostgreSQL major version, container base OS, Java major, scanner CLI and provider integration, a failure cannot be localized efficiently. Unless a documented target prerequisite forces a dependency change, stage optional modernization separately. When a dependency change is required, make that dependency explicit in the compatibility matrix and test the combined required path in rehearsal.

7. Failure: ignoring deprecation evidence

A green UI says nothing about your automation estate. After update, inspect API deprecation logs/headers and execute contract tests for every endpoint your provisioning, reporting and CI systems use. Migrate documented deprecated APIs before their removal window; never switch to undocumented internal endpoints to avoid updating a client.

8. Failure: keeping obsolete scanners indefinitely

Old scanners can lose support for modern server/runtime expectations. Current scanner guidance favors JRE auto-provisioning where supported; if it is disabled, modern Java is required. Inventory every scanner family—CLI, Maven, Gradle, .NET, NPM/Python integrations—and assign owners. A one-off successful scan does not justify indefinite retention of an unsupported scanner.

9. Causal failure map

10. Production shortcuts to reject

• Do not update production first.
• Do not repeatedly restart before preserving the first startup/migration error.
• Do not point the old server at a database already migrated by the new server.
• Do not manually edit SonarQube schema/search state to fake migration completion.
• Do not copy old third-party plugin directories blindly.
• Do not lower quality gates or suppress issues because analyzer results changed after update.
• Do not disable TLS verification or substitute administrator tokens to make integration tests pass.
• Do not replace the failing project key to erase history.

Knowledge check

Official references and version notes

• SonarQube downloads — current Community Build, commercial current release, and current LTA identities.
• Community Build — Determining the update path — direct same-year updates; December/January bridge rules across calendar years; no Community Build LTA concept.
• SonarQube Server — Release cycle model — two-month releases, yearly LTA, active-version support model, and YYYY.Release.Patch versioning.
• SonarQube Server — Determining the update path — intermediate LTA rules and update-path calculator.
• Community Build — Pre-update steps — read every intervening release note, back up the database, test first, and leave database disk headroom for migrations.
• Community Build — Performing the update — fresh installation/image, compatible plugins, configuration review, startup/migration and validation flow.
• Community Build — Post-update steps — scanner verification, database cleanup, service-path updates and API-deprecation review.
• Community Build — Other migration-related tasks — rollback requires restoring the pre-update database backup before switching back to the previous server.
• Community Build — Server host requirements — ZIP installations currently require JDK 21 or 25.
• Community Build — Database requirements — PostgreSQL 14–18 is supported in current Community Build.
• Plugin version matrix — verify every third-party plugin against the target before update.
• Deprecation policy — public APIs/features are deprecated before removal; migration planning must inventory those dependencies.
• SonarScanner CLI 8.1.0.6389 — scanner baseline used for post-update validation.
• Official SonarQube Docker tags — exact source/target image identities used by the rehearsal.