From e07e5bdd18203d07e4e071503b49403bdb51289f Mon Sep 17 00:00:00 2001 From: Valera V Harseko Date: Sun, 19 Jul 2026 08:49:42 +0300 Subject: [PATCH] Issue #746: remove stale opendj-server-legacy jar during upgrade Builds before #661 (fixed in 5.1.2) shipped a duplicate org.openidentityplatform.opendj.opendj-server-legacy.jar alongside opendj.jar in lib/. Unpacking a 5.1.2+ archive over such an install leaves that jar behind (it is no longer in the archive, so nothing overwrites or removes it). Because the launcher builds the classpath with the lib/* wildcard, the stale 5.1.1 jar can win and make the runtime report the old binary version, so the server refuses to start with "binary version does not match the installed version" after a successful upgrade. Register an upgrade task that deletes the leftover jar, and document the manual cleanup for upgrades to the already-released 5.1.2. --- .../main/asciidoc/install-guide/chap-upgrade.adoc | 7 +++++++ .../org/opends/server/tools/upgrade/Upgrade.java | 12 ++++++++++++ 2 files changed, 19 insertions(+) diff --git a/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc b/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc index c514e71c82..5077ecf8ff 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc @@ -108,6 +108,13 @@ The following steps describe how to upgrade OpenDJ directory server installed fr . (Optional) If you have not already backed up the current OpenDJ server, make a back up copy of the directory where OpenDJ is installed. . Unpack the new files from the .zip delivery over the current server files. ++ +[NOTE] +====== +When upgrading from a release before 5.1.2, first delete the stale `lib/org.openidentityplatform.opendj.opendj-server-legacy.jar` file (or clean out the `lib/` directory) before unpacking the new `.zip`. + +That file is a duplicate library that shipped in older distributions and is no longer part of the delivery, so unpacking the new archive over the existing installation neither overwrites nor removes it. Because the server builds its classpath from `lib/*`, the leftover jar makes the runtime report the old binary version, and the server fails to start after the upgrade with an error such as `The OpenDJ binary version '5.1.1...' does not match the installed version '5.1.2...'. Please run upgrade before continuing`. +====== . Run the `upgrade` command, described in xref:../reference/admin-tools-ref.adoc#upgrade-1[upgrade(1)] in the __Reference__, to bring OpenDJ configuration and application data up to date with the new binary and script files that you copied over the current server files. + diff --git a/opendj-server-legacy/src/main/java/org/opends/server/tools/upgrade/Upgrade.java b/opendj-server-legacy/src/main/java/org/opends/server/tools/upgrade/Upgrade.java index 132d3bf2a2..7b67cde876 100644 --- a/opendj-server-legacy/src/main/java/org/opends/server/tools/upgrade/Upgrade.java +++ b/opendj-server-legacy/src/main/java/org/opends/server/tools/upgrade/Upgrade.java @@ -12,6 +12,7 @@ * information: "Portions Copyright [year] [name of copyright owner]". * * Portions Copyright 2013-2016 ForgeRock AS. + * Portions Copyrighted 2026 3A Systems, LLC. */ package org.opends.server.tools.upgrade; @@ -609,6 +610,17 @@ public String toString() { register("4.0.0", moveSubordinateBaseDnToGlobalConfiguration()); register("4.0.0", removeTools("ldif-diff", "make-ldif", "dsjavaproperties")); + /* + * See issue #746. Builds before #661 (fixed in 5.1.2) shipped a duplicate + * org.openidentityplatform.opendj.opendj-server-legacy.jar alongside opendj.jar in lib/. + * When upgrading by unzipping a 5.1.2+ archive over such an installation, that jar is no + * longer part of the archive so it is neither overwritten nor removed. As the launcher builds + * the classpath with the lib/* wildcard, the stale jar makes the runtime report the old + * binary version and refuse to start with a version-mismatch error. Delete the leftover. + */ + register("5.1.2", + deleteFile(new File(libDirectory, "org.openidentityplatform.opendj.opendj-server-legacy.jar"))); + /* All upgrades will refresh the server configuration schema and generate a new upgrade folder. */ registerLast( performOEMMigrationIfNeeded(),