Upgrading to OIE 4.7.0: What Breaks and How to Fix It

Eclipse Open Integration Engine (OIE) 4.7.0 came out on October 21, 2026. It fixes the three flaws in CISA advisory ICSMA-26-253-01 (our write-up), and its dependency upgrades address 45 more CVEs in bundled components. If you run OIE 4.6.0, OIE 4.5.2 or open-source Mirth Connect 4.5.2, this is the release to move to.

Most of the server carries over: channels, code templates, configuration, users, passwords and message history. What breaks is a short list of changed defaults, and each one shows up at a bad moment: the first start, the first SOAP call, the first message from one particular sender. This post is that list, with the symptom and the fix for each.

The 4.7.0 changes that break upgrades

Change in 4.7.0	What you see	Fix
The SQL Server driver encrypts by default	The engine stops at startup with `PKIX path building failed`	Give SQL Server a certificate Java trusts; `trustServerCertificate=true` as a stopgap
Installers bundle Java 21	Every SOAP request to a Web Service Listener returns 500	Run on Java 17, or add one line to `custom.vmoptions`
XML with a DOCTYPE is rejected	XSLT steps, XML batch splitting and strict HL7 XML parsing fail on those messages	Send XML without the declaration
No `admin`/`admin` on a new database	Provisioning scripts can’t log in	Set `server.initialadminpassword`, or read the password from `logs/mirth.log`
Stricter validation	An HTTP Listener with a bad header-size value won’t start; misnamed metadata filters fail	Fix the value or the column name

Before you upgrade

The same room seen from the dim corridor, through its open doorway. Inside, the overbed light is on and the new floor is covered with protection boards, their seams taped and their near edge taped down just inside the threshold with blue painter's tape. The roll sits on the boards, the door stands open against the wall, the window at the far end is dark, and a short strip of tape marks a chip in the door frame's new paint. — Cover what is already there before the work starts.

Back up the engine’s database. 4.7.0 migrates the schema on first start, so going back to 4.6.0 means restoring that backup, not reinstalling the old version.
Export your channels and code templates. MirthSync pulls them into a Git repository, which gives you a copy to diff against after the upgrade.
Stop the engine, or its service, before you run the installer. If the old version is still running, the new one can’t start, because its ports are taken.
Upgrading from an archive (.tar.gz or .zip): extract it into a new folder and carry over conf/ and appdata/, which holds the keystore and, on Derby, the database. Don’t extract over the old installation. 4.7.0 changes many library versions, and the old jars would stay on the classpath beside the new ones.
Check your Java. 4.7.0 needs Java 17 or later, as 4.6.0 did. Installers that bundle Java now ship Eclipse Temurin 21 instead of Azul Zulu 17, so check any custom JVM options against 21.

Coming from 4.5.2

Skipping 4.6.0 brings its changes into the same upgrade:

Java 17 is the minimum.
Xerces and xml-apis are gone. Code templates and custom JARs that import org.apache.xerces classes have to move to javax.xml.parsers and org.xml.sax.
Logins are case-insensitive by default. Existing accounts with case-sensitive usernames keep working.

Channel XML exported from Mirth Connect 4.5.2 imports into 4.7.0 as it is.

What breaks, and how to fix it

Most of the wall is finished. The tape marks what is not.

Here they are in the order you are likely to meet them.

1. SQL Server: the engine stops at startup

4.7.0 bundles Microsoft’s SQL Server JDBC driver 10.2.4, up from 8.4.1. From 10.2 the driver encrypts by default and validates the server’s certificate, so a connection to a server without a trusted certificate, which used to work, now fails.

If the engine’s own database is on SQL Server, the engine logs this and exits:

Error establishing connection to database, aborting startup
...
PKIX path building failed

The same change reaches every Database Reader, Database Writer and script that connects through the Microsoft driver. Connections through jTDS are not affected.

The fix is a server certificate the engine’s Java runtime trusts: one issued by a CA already in its trust store, or your internal CA imported into it. If the engine runs on the Java that came with the installer, check that the import is still there after the next upgrade.

As a stopgap, add trustServerCertificate=true to database.url in conf/mirth.properties. The engine starts, but it no longer checks which server it is talking to, so treat it as temporary. For a channel’s connection, the same property goes on the connector’s URL.

database.url = jdbc:sqlserver://sql01.example.org:1433;databaseName=mirthdb;trustServerCertificate=true

2. Web Service Listener: every SOAP request returns 500

The installers’ move to Java 21 exposes a Web Service Listener bug that appears on any Java from 19 on, because Java 19 changed which classloader new pool threads inherit. On those versions, every SOAP POST to a Web Service Listener gets HTTP 500, and the log shows:

javax.xml.soap.SOAPException: Unable to create SAAJ meta-factory

The WSDL is still served, so a monitor that fetches ?wsdl stays green while every real call fails. That is the silent kind of failure our alerting guide is about.

Until a release carries the fix, there are two workarounds:

Run the engine on Java 17, which 4.7.0 still supports. Java 17 and 18 are not affected.
Or add one line to conf/custom.vmoptions and restart. This is the form for 4.6.0 and 4.7.0 on Linux, from upstream issue #509:

-classpath/a server-lib/javax/jaxws/javax.xml.soap-api-1.4.0.jar:server-lib/javax/jaxws/ext/saaj-impl-1.0.jar:server-lib/javax/jaxws/ext/stax-ex-1.8.jar:server-lib/javax/jaxws/ext/mimepull-1.9.7.jar:server-lib/javax/jakarta.activation-1.2.1.jar:server-lib/javax/jaxb/jaxb-api-2.4.0-b180725.0427.jar:server-lib/javax/jaxb/jaxb-runtime-2.4.0-b180725.0644.jar:server-lib/javax/jaxb/ext/istack-commons-runtime-3.0.6.jar:server-lib/javax/jaxb/ext/txw2-2.4.0-b180725.0644.jar

On Windows, upstream’s guidance is to separate the paths with ; instead of :. In Docker, pass the same line in the VMOPTIONS environment variable. The line puts SAAJ and JAXB on the classpath for the whole engine, so remove it once you’re on a release with the fix, #508, which was merged on November 1.

3. XML with a DOCTYPE is rejected

To close the two external-entity flaws in the advisory, 4.7.0 rejects a <!DOCTYPE> declaration in XML passed to:

an XSLT transformer step,
XML batch splitting, by element name, level or XPath,
the strict HL7 v2 XML parser.

A sender that starts every message with a DOCTYPE, often a reference to a DTD nobody fetches, now produces an error on every message. Ask the sender to drop it. If they can’t, strip it before the message reaches those steps, as long as the message doesn’t use entities the DTD defines. For an XSLT step, the channel’s preprocessor can do it. Batch splitting runs before the preprocessor, so there it has to happen upstream, in the channel that hands the message on.

Stylesheets themselves are not affected: xsl:import, xsl:include and document() keep working.

4. A new database has no admin/admin

An upgrade keeps your users and passwords. A new database is different: 4.7.0 no longer creates admin with the password admin. On first start it generates a 20-character password and writes it once to logs/mirth.log, and the first login asks you to change it.

************   Initial admin password is ...   ************

To choose the password yourself, set it before the first start. It only applies when the database is created; changing it later does nothing.

server.initialadminpassword = <your password>

Anything that signs in to a fresh server as admin/admin breaks: install scripts, Ansible roles, CI jobs that stand up a test engine, Docker setups.

New mirth.properties files also carry stricter password defaults: a 15-character minimum, password.retrylimit = 100 and password.lockoutperiod = 1 (one hour). An upgrade keeps your existing file, so you only get these if you set them.

5. Smaller changes that stop a connector or a script

HTTP Listener header size. The new maximum request-header size defaults to 8,192 bytes when a channel doesn’t set it. A value that is zero, negative or an unresolved variable stops the connector from starting. Check channel templates and settings pushed through the API.
Custom metadata search filters must name a configured column exactly, including case. A stale filter in a script or a saved API call is now rejected, and a synchronous request can return HTTP 500.
oieserver.ps1 is gone. Windows scripts and services that call it need the oieserver launcher.
The Administrator checks for JavaFX at startup and stops with a message if javafx.graphics is missing. Launch it with a runtime that includes JavaFX.
The CLI exits nonzero when it can’t sign in, connect or read its script, where before it could hang. Automation now sees failures it used to miss.
Jackson’s parsing limits. Jackson 2.18 caps nesting at 1,000 levels and a string value at 20 million characters. Test unusually deep or large JSON that custom code parses with Jackson.

6. Custom extensions and source builds

For teams with their own plugins or a fork:

EngineController adds an abstract five-argument dispatchRawMessage, and MessageServletInterface adds processBatchMessage. Custom implementations of either must add them.
The per-extension JNLP endpoint, /webstart/extensions/<extension>.jnlp, is removed. Extensions are listed in the main launch file, so custom launchers that fetched it need updating.
The Microsoft driver drops getAADSecretPrincipalId, and a synchronized global-map key that was never registered throws IllegalArgumentException instead of NullPointerException.
Source builds moved from Ant to Gradle: ./gradlew build -PdisableSigning=true.

A test pass before you close the window

Sign in. On a new server, take the generated password from logs/mirth.log.
Check that every channel deployed and started. A Database Reader or Writer that can’t reach SQL Server shows up here.
POST a real SOAP request to each Web Service Listener. A WSDL fetch proves nothing.
Replay a recent message from each XML sender through its XSLT steps and batch-splitting sources.
Run your API scripts and CI jobs, and check that they now fail loudly on errors.

What the next release adds

The same room's window. Beyond a parking deck, the next tower of the hospital is going up, its floor slabs and columns bare, a tower crane standing beside it with its jib out over the top floor. The privacy curtain is pushed back at the right, and a short strip of blue painter's tape marks a chip in the new window sill. — The next phase is already going up.

The Web Service Listener fix for Java 19 and later (#508) was merged upstream on November 1 and is waiting for a release.

The 4.7.0 release notes also list known advisories in the bundled PostgreSQL JDBC driver and Jackson Core. Each one applies only to a configuration or to custom code that the notes describe. Upstream also plans to remove the deprecated selectLimit parameter of the Database Connector’s table lookup and the remaining Java Security Manager code.

If you run OpenShare Engine

OpenShare Engine, Saga IT’s open-source build of OIE, moved onto 4.7.0 with 4.7.0-1 on October 29. Everything above applies, with four differences:

Newer libraries than upstream: Jackson 2.18.11, which resolves the two Jackson advisories upstream lists, and Microsoft SQL Server JDBC 13.2.1, which also encrypts by default, so section 1 applies unchanged. It keeps Jetty 12 and AWS SDK for Java 2.55.8 from the 4.6.0 builds.
Java 21 is the minimum, and the installers bundle Azul Zulu 21 with JavaFX. Running on Java 17 is not an option, so use the custom.vmoptions line for Web Service Listeners.
Update the admin-console plugin to 0.44.0 or later first. The 4.7.0 engine refuses older plugins. An installer downloaded from the OpenShare console installs a compatible one itself.
A new engine downloaded from the console gets its first admin password from the console, not from the log.

If you’d rather not run the upgrade yourself, we do OIE migration and support.

Frequently Asked Questions

What is the default admin password in OIE 4.7.0?

There isn't one. A new OIE 4.7.0 database no longer starts with admin/admin. On first startup the engine generates a 20-character password for the admin user, writes it once to logs/mirth.log, and asks you to change it at the first login. To choose it yourself, set server.initialadminpassword in conf/mirth.properties before the first start. An upgraded database keeps its existing users and passwords.

Can I upgrade from Mirth Connect 4.5.2 straight to OIE 4.7.0?

Yes. OIE continues the open-source Mirth Connect 4.5.2 code, and on first start a 4.7.0 server migrates an older database one version at a time. Back up the database first, because going back means restoring it. The 4.6.0 changes arrive in the same step: Java 17 is the minimum, and custom code that imports Xerces classes has to move to javax.xml.parsers.

Why does my Web Service Listener return HTTP 500 after upgrading to OIE 4.7.0?

The 4.7.0 installers bundle Java 21, and on Java 19 and later the Web Service Listener fails every SOAP request with "Unable to create SAAJ meta-factory" (upstream issue #509). The WSDL is still served, so a check that fetches it will pass. Run the engine on Java 17, or add the classpath line from the issue to conf/custom.vmoptions and restart. The fix is merged upstream and will ship in the next release.

Does OIE 4.7.0 still run on Java 17?

Yes. Java 17 has been the minimum since OIE 4.6.0 and still is. What changed is the bundled runtime: installers that include Java now ship Eclipse Temurin 21 instead of Azul Zulu 17. Saga IT's OpenShare Engine 4.7.0-1 is the exception, and needs Java 21.