Upgrade Planning, Version Support, Breaking Changes, Java Runtime Upgrades, and Rollback Strategy: Diagnostics, Failure Modes, Security, and Performance

1. Diagnostic sequence

1. Preserve startup logs, task history, version/build, Java, database and blob evidence.
2. Confirm the source→target path and every crossed threshold.
3. Check disk headroom, file handles, ownership, memory and temp directories.
4. Check Java selection and custom trust anchors.
5. Check database connectivity/schema migration state.
6. Check plugins/extensions and custom application-directory files.
7. Check blob backend and object-store errors.
8. Check required rebuild/migration tasks.
9. Run representative repository/client tests.
10. Correct the smallest supported cause or restore the checkpoint.

2. Failure: unsupported or wrong Java

Symptom: Nexus does not start, or external-JVM startup shows class/runtime errors.

Correction: confirm the actual JVM selected by the launcher and use Java 21/current compatibility guidance. Prefer the bundled runtime unless you intentionally manage an external JVM.

3. Failure: TLS integrations break after upgrade

Symptom: Nexus starts, but proxy repositories, LDAP, SAML metadata, or other HTTPS integrations fail certificate validation.

Cause: custom trust anchors existed only in the previous Java truststore and were not provisioned for the new bundled runtime.

Correction: restore the intended trust chain through the supported runtime/certificate mechanism. Do not disable TLS verification globally.

4. Failure: insufficient disk/temp space

Symptom: startup migration or rebuild fails, disk fills, or tasks repeatedly abort.

Correction: stop additional mutation, preserve logs, restore headroom, and follow version-specific recovery/retry guidance. Never delete blob files or database rows directly to make space.

5. Failure: community plugin breaks startup

Symptom: bundle/plugin resolution errors appear after the Nexus binary upgrade.

Correction: isolate/remove the unsupported plugin according to its own compatibility guidance and re-run from the preserved checkpoint if needed. Do not patch Nexus internals to keep an abandoned extension alive.

6. Failure: database migration does not complete

Distinguish database connectivity from schema migration. A reachable PostgreSQL server can still fail ownership, extension, permissions, capacity, or migration constraints. Preserve the exact migration error and do not point an older Nexus binary at partially upgraded schema state.

7. Failure: object-store behavior changes

Look for request-signing, multipart, checksum, retry, endpoint-style, or SDK compatibility errors. Compare the blob backend against the target release notes and the storage vendor’s compatibility matrix. A generic “S3 compatible” claim is not enough.

8. Failure: upgrade succeeds but clients change

Example: a write-once Ansible Galaxy duplicate publication can return a different HTTP status in a newer release. The correct fix may be updating client expectations, not changing Nexus security or write policy. Capture the exact HTTP exchange and compare it with release-specific guidance.

9. Failure: search appears incomplete

If the path crosses a version threshold requiring a search rebuild—or the target release notes call out incremental-indexing visibility—run the documented rebuild and observe task completion. Search/browse state is derived state; do not “repair” it by editing database tables.

10. Failure: operator tries a blind downgrade

11. Intentionally broken evidence classifier

symptoms={
 'startup':'PASS','proxyTls':'FAIL','database':'PASS','disk':'PASS',
 'pluginErrors':False,'crossedBundledJavaGate':True,'customCAWasInOldJVM':True
}
if symptoms['proxyTls']=='FAIL' and symptoms['crossedBundledJavaGate'] and symptoms['customCAWasInOldJVM']:
 print('PRIMARY HYPOTHESIS: trust anchor not provisioned to new runtime')
 print('SAFE ACTION: restore CA trust; keep TLS verification enabled')

Knowledge check

Summary and next step

Upgrade diagnosis follows the evidence chain from version/runtime to database/blob/task/client behavior and favors the least destructive supported correction.

Lesson 5 integrates the chapter into a complete upgrade-and-rollback drill.

Official references and version notes

• Sonatype: Upgrade Nexus Repository — standalone upgrade workflow, backups, install/data separation, vmoptions, TLS/custom configuration, and validation.
• Sonatype: Nexus Repository Upgrade Paths — version-crossing actions and compatibility gates.
• Sonatype: Nexus Repository 3 Versions Status — support status and community-plugin guidance.
• Sonatype: Nexus Repository 3.95.x Release Notes — current-line changes, known issues, and upgrade guidance.
• Sonatype: System Requirements — current Java 21 and operating requirements.
• Sonatype: Upgrade Nexus Repository Java Version — bundled Java behavior and external-JVM considerations.
• Sonatype: Java Runtime Compatibility Matrix — release-specific external Java compatibility.
• Sonatype: Prepare a Backup — coherent database/blob/configuration recovery preparation.
• Sonatype: Upgrading to 3.71.0 and Beyond — legacy OrientDB/H2 gates.
• Sonatype: Rolling Upgrades in High Availability — Pro/HA mixed-version and finalize-upgrade semantics.