Upgrade preparation

Prev Next

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.

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

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

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

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

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

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

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

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

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:

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.

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

  • 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

  • Backing up SAP libraries: If you use SAP connectivity, back up the libraries before the upgrade and restore them afterward. → Pre-upgrade checklist (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

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

    • 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

    • Review the property "profile.backup.handler.implementation" to opt-in on the new optimized performance. See also: LDP Release 26.3.0

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

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

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

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

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

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.

Topic

Link

Generic pre-upgrade checklist.

Pre-upgrade checklist

Environment selection and OS-specific steps.

Select installation instructions for your environment

Java upgrade – overview and next steps.

Java upgrade overview

Release and update policy.

Platform update guide

Release Notes 26.3.

Release notes

Do you have any questions or need help with the upgrade? Please contact Lobster Support.

Related articles