Liquibase - Upgrade from OJDBC 8 to OJDBC 11 - DB then complains about a missing Orai18n jar file

General Discussion
1

Hi,

we have upgraded from LPM OJDBC8 drivers to OJDBC 11, but after an update, Liquibase complains about a missing orai18n.jar, because our DB is using an Eastern European character set. However, when we were running a pure OJDBC8 drivers from LPM, this was never an issue. To my knowledge, there shouldn’t be any changes between OJDBC 8 and 11 in this regard.

We are using following Dockerfile section:

RUN lpm update
RUN lpm add oracle-ojdbc8 --global

USER root

RUN apt-get update && apt-get install -y apt-utils && apt-get upgrade -y && apt-get install -y curl jq openssh-client

And we have simply switched the LPM package to ojdbc11


RUN lpm update
RUN lpm add oracle-ojdbc11 --global

USER root

RUN apt-get update && apt-get install -y apt-utils && apt-get upgrade -y && apt-get install -y curl jq openssh-client

However, then the DB returns an ORA-17056 error. Here is a Liquibase log:

Starting Liquibase at 20:34:28 using Java 21.0.11 (version 5.0.3 #10665 built at 2026-05-13 17:55+0000)

Liquibase Version: 5.0.3

WARNING:

Liquibase detected the following invalid Community LIQUIBASE_* environment variables:

- LIQUIBASE_IMAGE_NAME

- LIQUIBASE_IMAGE_TAG

Find the list of valid environment variables at Pro 4.33: What are Liquibase environment variables?

ERROR: Exception Details

ERROR: Exception Primary Class: SQLException

ERROR: Exception Primary Reason: ORA-17056: Non-supported character set (add orai18n.jar in the classpath): EE8ISO8859P2

ERROR: Exception Primary Source: 5.0.3

Unexpected error running Liquibase: Connection could not be created to jdbc:oracle:thin:@oradbp-scan.server.cetin:1535/ZISP with driver oracle.jdbc.OracleDriver. ORA-17056: Non-supported character set (add orai18n.jar in the classpath): EE8ISO8859P2

And we are calling Liquibase like this:

          liquibase --changelog-file "../../dbchangelog.xml"  --log-file "../../../reports/${f}.log" --username=${oracle_user} --password=${oracle_pasword}  --url jdbc:oracle:thin:@${ORACLE_SERVER}:${ORACLE_PORT}/${ORACLE_SERVICE} --logLevel=INFO update -Duser.timezone="Europe/Prague"

The only thing we had to do, is to add a dynamic orai18n.jar file download based on the Oracle driver version from the LPM package:

RUN OJDBC_JAR=$(ls /liquibase/lib/ojdbc11-*.jar) && \
    OJDBC_VERSION=$(basename "$OJDBC_JAR" | sed -E 's/ojdbc11-(.*)\.jar/\1/') && \
    echo "Matching orai18n.jar to installed ojdbc11 version: ${OJDBC_VERSION}" && \
    curl -fL -o /liquibase/lib/orai18n.jar "https://repo1.maven.org/maven2/com/oracle/database/nls/orai18n/${OJDBC_VERSION}/orai18n-${OJDBC_VERSION}.jar" && \
    chmod 644 /liquibase/lib/orai18n.jar

However, I don’t understand, why this change was not necessary with OJDBC 8. Any ideas? From what Google is telling me, there shouldn’t be any difference between them in this area.

2

A couple of things going on here:

1. ORA-17056 is client-side, not from the DB. The thin driver has to construct a CharacterSet object for your DB charset at connect time. The base ojdbc jar only embeds a small set & EE8ISO8859P2 has never been in that list, for any ojdbc jar. It has always required orai18n.jar. Oracle’s globalization docs are word-for-word identical for ojdbc8.jar and ojdbc11.jar on this point, so you’re right that there’s no 8-vs-11 difference.

2. The 8/11 suffix is the JDK target, not the driver release. Both are built from the same source at a given release. What almost certainly changed is the driver version, via Docker layer caching.

Your Dockerfile doesn’t pin a version, so lpm add oracle-ojdbc8 --global resolved to whatever was latest the first time that layer was built. This could have been 19.x or 21.x. Whatever the driver version, it was then cached indefinitely on every rebuild since. Editing the line to oracle-ojdbc11 invalidated the cache, so lpm update + lpm add pulled fresh and you got 23.26.3.0.0. So the real jump could have been something like 19.x → 23.26.x, not 8 → 11.

The easiest way to confirm this is to rebuild the old ojdbc8 Dockerfile with --no-cache. If it now fails the same way, 8 vs 11 was never the cause. It was likely the underlying driver update.

Two Suggestions & One Question :

  • Pin the driver version so this can’t drift silently again: lpm add oracle-ojdbc11@23.26.3.0.0 --global. Your orai18n download will then always match.
  • Your dynamic orai18n fetch is the right approach for now. LPM genuinely has no NLS package today (the Oracle entries are only ojdbc8/10/11, oraclepki, osdt_core, osdt_cert). Since orai18n has to version-match the driver, LPM is the obvious place to handle that, so you may want to open an enhancement to add it as a package.
  • Did you also upgrade Liquibase at the same time? The LIQUIBASE_IMAGE_NAME / LIQUIBASE_IMAGE_TAG got me thinking you may be on a newer release than before, which would be a second variable worth ruling out. The 5.x distribution no longer ships drivers by default, so if you were working with 4.x the orai18n.jar may have resolved elsewhere, explaining the difference.
3

Thank you! I think these tags are actually already deprecated, but we are running on Liquibase 5.x, and for quite a while now, and this was working correctly with the OJDBC 8 drivers, which is actually the reason it got me so confused.

Thank you for detailed explanation!