--- title: "Upgrade preparation" slug: "upgrade-landing-page" tags: ["Java Compatibility", "Lobster Data Platform", "Version Upgrade"] status: "update" updated: 2026-10-27T09:03:09Z published: 2026-10-27T09:03:09Z canonical: "docs.lobstersoftware.com/upgrade-landing-page" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.lobstersoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # Upgrade preparation This page consolidates all requirements, mandatory actions, and related resources you need for a successful upgrade to **Lobster Data Platform** version 26.3 and later. Work through the sections in order before starting the upgrade in your production environment. > [!WARNING] > **IMPORTANT:** > > An upgrade may require specific configurations and installations, some of which must be implemented and tested in a test environment – separately from a Java upgrade – before upgrading the production system. Upgrading without following these steps may result in the platform being unable to restart or in connections to databases and third-party systems failing. ## Changes at a glance | Change | Severity | Impact | Details | | --- | --- | --- | --- | | Migration to OpenJDK 21 | 🔴 Required from 26.4 | OpenJDK 11 has reached end-of-life. Starting with release 26.4, OpenJDK 21 is required. Versions prior to 26.4 continue to run on OpenJDK 11; versions 26.3 and 26.2 support both OpenJDK 21 and OpenJDK 11. See the table under "Upgrade paths" below. **NOTE:** - The updater will abort the installation of 26.4 if it does not detect OpenJDK 21. - If you update to OpenJDK 21, you must also use the new Lobster Application Wrapper. | [Java upgrade overview](/v1/docs/en/java-upgrade-info) | | New wrapper installation process | 🔴 Required | Release 26.3 uses a new wrapper. The start/stop mechanisms have changed. Existing configurations must be updated for the Lobster Application Wrapper to function correctly. | [Lobster Application Wrapper](/v1/docs/en/application-wrapper) | | JasperReports libraries and dependencies | 🔴 Required | When migrating from 26.2.4 or older, you must remove all existing JasperReports libraries and dependencies from the `extlib` folder to avoid classpath conflicts. | | | JDBC driver compatibility | 🔴 Important | **Outdated drivers** cause connection failures under **OpenJDK 21**. This particularly affects the MS SQL Server — recurring issues have been observed when the driver is not updated before upgrading the JDK. | [JDBC driver compatibility assessment](/v1/docs/en/jdbc-drivers) | | Bridge systems | 🟡 Conditional | The Bridge uses the same version of Java as **Lobster Data Platform**. Therefore, when upgrading to 26.4, your Bridge systems must also be upgraded to OpenJDK 21. | [Attended bridge installation](/v1/docs/en/creating-a-bridge-connection-on-the-platform) | | JDOM2 migration | 🟡 Conditional | Only applies if you use custom code (Execute scripts, custom Java classes) that imports JDOM classes. This migration is required **regardless of the Java version in use**, including Java 11. | [JDOM1 to JDOM2 migration](/v1/docs/en/jdom1-to-jdom2-migration) | | TLS default settings | 🟡 Conditional | TLS 1.0 and 1.1 are disabled by default under **OpenJDK 21**. Connections to legacy systems that do not support TLS 1.2+ will fail. | [TLS Java changes](/v1/docs/en/tls-java-changes) | | Informix as hub database | 🟡 Not supported | All Informix JDBC JARs have been removed (applies to 26.3, but also to 26.2.0 and 25.1.11). For non-hub scenarios: provide the driver yourself under `IS/extlib`. | [JDBC driver compatibility assessment](/v1/docs/en/jdbc-drivers) | | Character encoding UTF-8 | 🔵 Notice | The default character encoding under **OpenJDK 21** is now always UTF-8 (including on Windows). Check log files, CSV exports, and database imports if you have not previously set an explicit encoding. | [Upgrade from Java 11 to Java 21](/v1/docs/en/upgrading-from-java-11-to-java-21) | ## Upgrade paths Use the following table to determine which additional steps apply to your starting point. If you have skipped one or more intermediate versions, you must account for the changes documented there cumulatively. | From version ↓ | **To version →** | | --- | --- | | **25.1.x LTS** | **26.1.x** | **26.2.x** | **26.3.x** | **26.4.x** | | **>= 4.6.14** | ✅ | 🚫 | 🚫 | 🚫 | 🚫 | | **25.1.x LTS** | | ✅ | ✅ | ✅ | ✅ | | **26.1.x** | N/A | | ✅ | ✅ | ✅ | | **26.2.x** | N/A | N/A | | ✅ | ✅ | | **26.3.x** | N/A | N/A | N/A | | ✅ | | **Supported Java version** | Java 11 | Java 11 | Java 11 or 21 | Java 11 or 21 | Java 21 | ✅ – recommended, 🚫– not recommended, N/A – not applicable **IMPORTANT:** Starting with version 26.3, Java 21 is the recommended runtime environment. Although Java 11 is still supported in this version, regular vendor support for Java 11 has ended. Starting with version 26.4, only Java 21 will be supported. See also: - [Select installation instructions for your environment](/v1/docs/en/select-your-environment#local-installation-upgrades) - [One-click migration from older systems](/v1/docs/en/migration-from-older-systems) - [Release notes](/v1/docs/en/release-notes) ## Step-by-step checklist The following checklist walks you through all required actions. Complete the steps in the order shown. ### Step 1 – Preparation - [ ] **Create a backup:** Back up the complete Lobster installation directory and the repository database. → [Pre-upgrade checklist](/v1/docs/en/before-starting-an-update#preupgrade-checklist). - [ ] **Verify upgrade path:** Determine your starting point (see the "Upgrade paths" section above and review all cumulatively important changes. ### Step 2 – Check and update dependencies - [ ] **Upgrade to Java 21** (recommended starting with version 26.3, required from version 26.4 onward): Follow the [Before upgrading Java – Checklist](/v1/docs/en/before-java-upgrade). It will guide you through JDK deployment, JDBC driver compatibility, and TLS settings. - [ ] **Customize wrapper configuration**: Starting with version 26.3, a new wrapper will be used for the startup function. The new wrapper uses the `platform.json` and `wrapper.json` files instead of `wrapper.conf`. Transfer your existing settings to these new files. → [Lobster Application Wrapper](/v1/docs/en/application-wrapper) - [ ] **Migrating custom code to JDOM2**: This only applies to you if you use Execute Scripts or your own Java classes that import JDOM classes. The migration is also required in Java 11. → [JDOM1 to JDOM2 Migration](/v1/docs/en/jdom1-to-jdom2-migration) - [ ] **Backing up SAP libraries**: If you use SAP connectivity, back up the libraries before the upgrade and restore them afterward. → [Pre-upgrade checklist](/v1/docs/en/before-starting-an-update#sap-libraries) (under the "SAP libraries" section) - [ ] **Update external drivers in** `./extlib`**:**These are not modified during the update. Check the versions and replace them as needed before the upgrade. ### Step 3 – Staging test - [ ] **Perform the full upgrade on your test system:** Apply the platform update, Java switch, driver update, and wrapper change together in a non-production environment. - [ ] **Run end-to-end tests:** - Database access (all database types in use). - Reporting and BI integrations. - SAP connectivity (if applicable). - TLS-secured connections to third-party systems. - Execute scripts and custom code using JDOM. - CSV/file exports for correct character encoding. - [ ] **Check Java version status in the UI:** After the restart, the Java icon in the system info bar must no longer show a red exclamation mark. → [Java version status check](/v1/docs/en/java-version-status-check) ### Step 4 – Production upgrade - [ ] **Schedule a maintenance window:** Coordinate the window with your team. Plan it during a period of low data throughput. - [ ] **Run the upgrade:** Follow the step-by-step guide for your environment: [Windows](/v1/docs/en/select-your-environment#windows-linux-dmz-high-availability) | [Linux](/v1/docs/en/select-your-environment#windows-linux-dmz-high-availability) | [DMZ](/v1/docs/en/select-your-environment#windows-linux-dmz-high-availability) | [High availability](/v1/docs/en/select-your-environment#windows-linux-dmz-high-availability) - [ ] **Post-upgrade verification:** After the restart, confirm the following: - Platform version number in the UI: **26.3.x.** - Java icon without a red exclamation mark. - Log file `./logs/console.txt`: no `ClassNotFoundException`, no `NoSuchMethodError`, no TLS Handshake errors. - All database connections reachable (connection test in the UI). - At least one representative Job completed successfully. - [ ] Please also follow these important changes and instructions: - Review the **JasperReports Library** if not coming from 26.2.4 or up. See also: [LDP Release 26.2.4](/v1/docs/en/ldp-release-26-2-4#ldp7202). - If you would like to use the legacy **OpenAPI viewer** from specific hosts, check the "hub.datawizard.api.viewer.whitelist" property. See also: [LDP Release 26.3.0](/v1/docs/en/ldp-release-26-3-0#ldp76451) - Review the **property** "profile.backup.handler.implementation" to opt-in on the new optimized performance. See also: [LDP Release 26.3.0](/v1/docs/en/ldp-release-26-3-0#ldp57241) ## Known issues and workarounds | Symptom | Cause | Workaround | | --- | --- | --- | | Connection errors to MS SQL Server after upgrade. | JDBC driver is incompatible with OpenJDK 21 (commonly `mssql-jdbc-11.x` or older). | Update the driver to `mssql-jdbc-12.6` or later. → [JDBC driver compatibility assessment](/v1/docs/en/jdbc-drivers) | | TLS handshake errors when connecting to legacy systems. | The remote system only supports TLS 1.0/1.1, which is disabled by default under OpenJDK 21. | Update the remote system. If not immediately possible, configure a temporary exception in `java.security`. → [TLS Java changes](/v1/docs/en/tls-java-changes) | | `ClassNotFoundException: org.jdom.*` | Custom code still references the legacy JDOM 1.x package prefix `org.jdom`. | Update imports to `org.jdom2`. → [JDOM1 to JDOM2 migration](/v1/docs/en/jdom1-to-jdom2-migration) | | Service fails to start / wrapper error. | Legacy startup mechanisms (for example, `execute.sh`) are not disabled. Custom JVM parameters were not transferred to `platform.json`. | Update the wrapper configuration per the guide. → [Lobster Application Wrapper](/v1/docs/en/application-wrapper) | | Character encoding in CSV exports differs. | OpenJDK 21 defaults to UTF-8 instead of Cp1252 (Windows). | Set the encoding explicitly, or temporarily use `-Dfile.encoding=WINDOWS-1252` as a JVM parameter. → [Upgrade from Java 11 to Java 21](/v1/docs/en/upgrading-from-java-11-to-java-21) | ## Estimated downtime | Component | Estimate | | --- | --- | | Install the platform update | Approx. 1–10 minutes (depends on disk speed and antivirus scanner). | | JDK switch + wrapper update | Approx. 5–15 minutes (manual configuration steps). | | Platform restart | Depends on system size and running jobs. Use `./force_stop` to limit wait time. | When in doubt, refer to the historical start/stop times of your system to estimate the expected downtime realistically. ## Related resources | Topic | Link | | --- | --- | | Generic pre-upgrade checklist. | [Pre-upgrade checklist](/v1/docs/en/before-starting-an-update#preupgrade-checklist) | | Environment selection and OS-specific steps. | [Select installation instructions for your environment](/v1/docs/en/select-your-environment#type-of-installation) | | Java upgrade – overview and next steps. | [Java upgrade overview](/v1/docs/en/java-upgrade-info#why-java-21) | | Release and update policy. | [Platform update guide](/v1/docs/en/platform-update-guide) | | Release Notes 26.3. | [Release notes](/v1/docs/en/release-notes) | --- Do you have any questions or need help with the upgrade? Please contact Lobster Support. The TLS handshake is the negotiation at the start of a TLS connection: both sides agree on methods, and the server identifies itself with its certificate, which the other side verifies. If the TLS handshake fails, no connection is established; with AS2, for instance, the message is not delivered. Execution instance that arises when an **inbound agent** of a profile accepts data. The platform creates a backup file and processes the **job** through all profile phases. Running, successful, and failed jobs are visible in **the Control Center** .