Falha de Conexão do IronPdfEngine a partir de um JAR Completo

Atualizado:julho 2, 2026

Translated

View the article in English

Quando sua aplicação IronPDF for Java está empacotada como um JAR completo (uber), o cliente não consegue se conectar ao mecanismo de renderização interno. IronPdfEngine inicia e escuta na porta correta, mas o cliente Java faz 20 tentativas de conexão e falha toda vez.

Failed to connect to IronPdfEngine after 20 attempts

A falha vem da fusão de cada dependência em um único JAR sombreado autônomo (uber) — por exemplo, com o plugin Maven Shade ou Gradle Shadow. Arquivos de recurso sobrepostos das dependências fundidas impedem o cliente Java de alcançar o subprocesso IronPdfEngine: o mecanismo é iniciado e abre a porta esperada, mas o cliente nunca consegue se conectar e desiste após 20 tentativas. Manter cada dependência como seu próprio arquivo no classpath evita o conflito.

Solução

Construa o projeto normalmente, copie suas dependências para uma pasta, depois inicie o aplicativo apontando o Java diretamente para esses arquivos em vez de usar java -jar.

1. Construa o Projeto

mvn clean package

mvn clean package

SHELL

2. Copie Dependências de Execução

Coloque cada biblioteca em target/libs como JARs separados, que é o que a abordagem classpath precisa:

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

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

SHELL

3. Execute a partir do Classpath

Inicie o aplicativo contra o classpath expandido em vez do JAR completo. Substitua com.example.Main pela sua classe principal real.

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

A única diferença entre os dois comandos é o separador classpath: um ponto e vírgula (;) no Windows, dois pontos (:) no Linux e macOS.

Dicas de Depuração

O que não funciona: executar a partir do JAR completo inicia IronPdfEngine com sucesso, mas o cliente Java nunca se conecta.
--add-opens sozinho não é suficiente: adicionar a flag JVM enquanto ainda executando a partir de um JAR completo não corrige a falha de conexão. A flag importa somente junto com o lançamento do classpath acima.
Strings de versão PDF/A: se seu código passar uma versão PDF/A como um argumento de string, use PdfA2a, não PdfAVersions.PdfA2a.

Curtis Chau

Converse agora mesmo com a equipe de engenharia.

Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais ...