IronPDF Java: IronPdfEngine Connection Failure When Running from a Fat JAR

Overview

IronPDF Java cannot connect to its internal rendering engine (IronPdfEngine) when the application is packaged as a fat/uber JAR — a single file that bundles the application and all its dependencies together. IronPdfEngine starts up and listens on the correct port, but the Java client makes 20 connection attempts and fails every time. The fix is to run from an explicit classpath instead of a fat JAR.

Environment

• Language/Runtime: Java (JDK 21)
• Build Tool: Maven
• Packaging: Fat/uber JAR (jar-with-dependencies)
   

Version Metadata

• Version Found: 2026.3.1
• Version Resolved: N/A

Cause

Running IronPDF Java from a fat JAR is not supported. When all dependencies are merged into one JAR file, something in the packaging breaks the communication between the Java client and the IronPdfEngine subprocess. IronPdfEngine starts and opens the expected port, but the client cannot reach it and gives up after 20 retries. Running from an explicit classpath — where each dependency stays as its own file — avoids the conflict.

Solution

Instead of running from a fat JAR, build the project normally, copy the dependencies to a folder, then launch the app by pointing Java at those files directly.

Step 1 — Build the project.

mvn clean package

Step 2 — Copy all runtime dependencies to a folder.

This puts every library file into target/libs as separate JARs, which is what the classpath approach needs.

mvn dependency:copy-dependencies -DoutputDirectory=target/libs

Step 3 — Run the application from the classpath. (Recommended)

Use the commands below instead of java -jar. Replace com.example.Main with your actual main class name.

Windows:

java --add-opens java.base/java.nio=ALL-UNNAMED -cp "target/classes;target/libs/*" com.example.Main

Linux / macOS:

java --add-opens java.base/java.nio=ALL-UNNAMED -cp "target/classes:target/libs/*" com.example.Main

PDF/A version strings: If your code passes a PDF/A version as a string argument, use PdfA2a — not PdfAVersions.PdfA2a.

• Running from the fat/uber JAR — IronPdfEngine launches successfully but the Java client never connects.
• Adding --add-opens flags alone while still running from a fat JAR — the JVM flag by itself does not fix the connection failure.