IronPdfEngine 연결 실패 from a Fat JAR

Updated: 2026년 7월 3일

IronPDF for Java 응용 프로그램이 fat (uber) JAR로 패키징될 때, 클라이언트는 내부 렌더링 엔진에 연결할 수 없습니다. IronPdfEngine가 시작되고 올바른 포트에서 수신 대기하지만, Java 클라이언트는 20번의 연결 시도를 했으나 매번 실패합니다.

Failed to connect to IronPdfEngine after 20 attempts

Failed to connect to IronPdfEngine after 20 attempts

Text

이 실패는 모든 종속성을 하나의 자체 조립된 쉐이딩(uber) JAR로 병합하는 데서 발생합니다. 예를 들어 Maven Shade 또는 Gradle Shadow 플러그인을 사용할 때입니다. 병합된 종속성의 중복 리소스 파일로 인해 Java 클라이언트가 IronPdfEngine 하위 프로세스를 도달하지 못하게 합니다: 엔진은 실행되고 기대된 포트를 열지만, 클라이언트는 결코 연결할 수 없으며 20번의 재시도 후 포기합니다. 클래스 경로에 각 종속성을 자체 파일로 유지하면 충돌을 피할 수 있습니다.

해결책

프로젝트를 정상적으로 빌드하고 종속성을 폴더에 복사한 다음, java -jar을 사용하는 대신 Java에서 해당 파일을 직접 가리켜 앱을 실행합니다.

1. 프로젝트 빌드

mvn clean package

mvn clean package

SHELL

2. 런타임 종속성 복사

각 라이브러리를 별도의 JAR로 target/libs에 배치합니다. 이는 클래스 경로 접근 방식이 필요로 하는 것입니다:

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

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

SHELL

3. 클래스 경로에서 실행

Fat JAR이 아닌 폭발된 클래스 경로에서 앱을 실행합니다. com.example.Main을 실제 메인 클래스로 교체하세요.

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

두 명령의 유일한 차이는 클래스 경로 구분자입니다: Windows에서는 세미콜론(;), Linux와 macOS에서는 콜론(:)입니다.

디버그 팁

작동하지 않는 방식: fat JAR에서 실행하면 IronPdfEngine이 성공적으로 실행되지만 Java 클라이언트는 결코 연결하지 않습니다.
--add-opens만으로는 충분하지 않습니다: JVM 플래그를 추가하면서 여전히 fat JAR에서 실행하는 것은 연결 실패를 해결하지 않습니다. 플래그는 위에서 설명한 클래스 경로 실행과 함께일 때만 중요합니다.
PDF/A 버전 문자열: 코드가 PDF/A 버전을 문자열 인수로 전달할 때, PdfA2a을 사용하세요, PdfAVersions.PdfA2a가 아니라.

Curtis Chau

지금 바로 엔지니어링 팀과 채팅하세요

기술 문서 작성자

커티스 차우는 칼턴 대학교에서 컴퓨터 과학 학사 학위를 취득했으며, Node.js, TypeScript, JavaScript, React를 전문으로 하는 프론트엔드 개발자입니다. 직관적이고 미적으로 뛰어난 사용자 인터페이스를 만드는 데 열정을 가진 그는 최신 프레임워크를 활용하고, 잘 구성되고 시각적으로 매력적인 매뉴얼을 제작하는 것을 즐깁니다.

...

더 읽어보기