Error de conexión de IronPdfEngine desde un Fat JAR

Updated: 3 de julio de 2026

Cuando tu aplicación IronPDF for Java se empaqueta como un JAR gordo (uber), el cliente no puede conectarse al motor de renderizado interno. IronPdfEngine inicia y escucha en el puerto correcto, pero el cliente Java realiza 20 intentos de conexión y falla cada vez.

Failed to connect to IronPdfEngine after 20 attempts

Failed to connect to IronPdfEngine after 20 attempts

Text

La falla proviene de combinar cada dependencia en un único JAR ensombrecido (uber) autocompuesto, por ejemplo con el plugin Maven Shade o Gradle Shadow. Los archivos de recursos superpuestos de las dependencias fusionadas impiden que el cliente Java alcance el subproceso IronPdfEngine: el motor se lanza y abre el puerto esperado, pero el cliente nunca puede conectarse y se rinde después de 20 reintentos. Mantener cada dependencia como su propio archivo en el classpath evita el conflicto.

Solución

Compila el proyecto normalmente, copia sus dependencias en una carpeta, luego lanza la aplicación apuntando Java a esos archivos directamente en lugar de usar java -jar.

1. Compila el proyecto

mvn clean package

mvn clean package

SHELL

2. Copia las dependencias de tiempo de ejecución

Coloca cada biblioteca en target/libs como JARs separados, que es lo que necesita el enfoque del classpath:

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

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

SHELL

3. Ejecuta desde el classpath

Lanza la aplicación contra el classpath explotado en lugar del JAR gordo. Reemplaza com.example.Main con tu clase principal actual.

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

La única diferencia entre los dos comandos es el separador de classpath: un punto y coma (;) en Windows, dos puntos (:) en Linux y macOS.

Consejos para depuración

Lo que no funciona: ejecutar desde el JAR gordo lanza IronPdfEngine exitosamente, pero el cliente Java nunca se conecta.
--add-opens solo no es suficiente: agregar la bandera JVM mientras aún se ejecuta desde un JAR gordo no soluciona el error de conexión. La bandera sólo importa junto con el lanzamiento desde el classpath mencionado anteriormente.
Cadenas de versión PDF/A: si tu código pasa una versión PDF/A como un argumento de cadena, usa PdfA2a, no PdfAVersions.PdfA2a.

Curtis Chau

Chatea con el equipo de ingeniería ahora

Escritor Técnico

Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.

...