[#746] remove stale opendj-server-legacy jar during upgrade (#751)

Author: vharseko

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.
 +

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(),