IronPdfEngine Connection Failure from a Fat JAR

Updated: July 3, 2026

When your IronPDF for Java application is packaged as a fat (uber) JAR, the client cannot connect to the internal rendering engine. IronPdfEngine starts and listens on the correct port, but the Java client makes 20 connection attempts and fails every time.

Failed to connect to IronPdfEngine after 20 attempts

Failed to connect to IronPdfEngine after 20 attempts

Text

The failure comes from merging every dependency into a single self-assembled shaded (uber) JAR - for example with the Maven Shade or Gradle Shadow plugin. Overlapping resource files from the merged dependencies stop the Java client from reaching the IronPdfEngine subprocess: the engine launches and opens the expected port, but the client can never connect and gives up after 20 retries. Keeping each dependency as its own file on the classpath avoids the conflict.

Solution

Build the project normally, copy its dependencies into a folder, then launch the app by pointing Java at those files directly instead of using java -jar.

1. Build the Project

mvn clean package

mvn clean package

SHELL

2. Copy Runtime Dependencies

Place every library into target/libs as separate JARs, which is what the classpath approach needs:

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

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

SHELL

3. Run from the Classpath

Launch the app against the exploded classpath rather than the fat JAR. Replace com.example.Main with your actual main class.

Windows:

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

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

SHELL

Linux / macOS:

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

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

SHELL

The only difference between the two commands is the classpath separator: a semicolon (;) on Windows, a colon (:) on Linux and macOS.

Debug Tips

What does not work: running from the fat JAR launches IronPdfEngine successfully, but the Java client never connects.
--add-opens alone is not enough: adding the JVM flag while still running from a fat JAR does not fix the connection failure. The flag matters only alongside the classpath launch above.
PDF/A version strings: if your code passes a PDF/A version as a string argument, use PdfA2a, not PdfAVersions.PdfA2a.

Curtis Chau

Chat with engineering team now

Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...