jar 파일 실행시 Error initializing QuantumRenderer: no suitable pipeline found 에러 해결하기 (feat: JavaFX 의존성)

현재 노트: KR-010.70 a
상위 분류: [[]]

안녕하세요! "자바의 신"과 같은 책이나 강의에서 만든 jar 애플리케이션 실행시 발생한 에러가 발생하여 트러블 슈팅을 수행했는데요, 이 과정이 일반적인 jar에서도 생길 수 있다고 느껴 나중에 언젠가는 쓰일 것 같아 기록합니다.

초기 단순한 -jar 명령어 사용시 발생한 에러 로그

Graphics Device initialization failed for :  d3d, sw
Error initializing QuantumRenderer: no suitable pipeline found
java.lang.RuntimeException: java.lang.RuntimeException: Error initializing Quant

1. 근본 원인: JavaFX의 Java와 독립된 형태로 분리됨

이 문제의 근본 원인은 바로 Java 9부터 JavaFX가 JDK에서 완전히 분리되었기 때문입니다.

과거 (Java 8 시절): JavaFX는 JDK에 포함된 '기본 기능'이었습니다. 별도 설정 없이도 당연하게 사용할 수 있었죠.
현재 (Java 11 이후): JavaFX는 이제 우리가 직접 다운로드하고 설정해야 하는 '외부 라이브러리'가 되었습니다.

오라클 자바 발표 출처: https://blogs.oracle.com/java/post/the-future-of-javafx-and-other-java-client-roadmap-updates
이 '분리' 때문에, 우리는 이제 java 명령어를 실행할 때 JavaFX의 위치와 사용할 모듈을 명시적으로 알려주어야만 합니다. 그렇지 않으면 Java는 길을 잃고 헤매며 위와 같은 에러를 뱉어냅니다.

2. 에러 해결 여정: 단계별 진단과 처방

실제 문제 해결 과정을 시간 순서대로 따라가 보겠습니다.

상황 1: `No toolkit found` 에러 발생

가장 처음 마주하는 에러입니다. "UI를 그릴 도구가 없다"는 뜻으로, Java가 JavaFX의 존재 자체를 인식하지 못하는 상태입니다.

진단: JavaFX 라이브러리 경로가 지정되지 않았습니다.
해결책:
1. 먼저, **Gluon 공식 사이트**에서 내 JDK 버전 및 운영체제에 맞는 JavaFX SDK를 다운로드합니다.
2. java 명령어에 --module-path와 --add-modules 옵션을 추가하여 JavaFX의 위치와 사용할 모듈을 알려줍니다.
1차 시도: JavaFX의 위치와 기본 모듈(controls, fxml)을 알려줌

java --module-path [다운로드한 JavaFX SDK lib 폴더] --add-modules javafx.controls,javafx.fxml -jar myapp.jar

상황 2: `IllegalAccessError` 에러 발생

Caused by: java.lang.IllegalAccessError: superclass access check failed: class com.sun.javafx.sg.prism.web.NGWebView (in unnamed module @0x24e5cbe9) cannot access class com.sun.javafx.sg.prism.NGGroup (in module javafx.graphics) because module javafx.graphics does not export com.sun.javafx.sg.prism to unnamed module @0x24e5cbe9

위 문제를 해결하자, 이번엔 IllegalAccessError 라는 새로운 에러가 나타났습니다. "접근 권한이 없다"는 뜻입니다.

진단: 앱의 특정 기능(WebView 등)이 JavaFX의 '내부 전용 기능'에 접근하려 했으나, Java의 모듈 시스템 보안 규칙에 의해 차단되었습니다.
해결책: --add-exports 옵션을 추가하여, 필요한 내부 기능에 접근할 수 있도록 '특별 허가증'을 발급해 줍니다. 또한 WebView에 필요한 javafx.web 모듈도 추가합니다.

3. 최종 해결: 완전한 실행 명령어 공식

위 과정을 모두 거쳐 완성된, 현대 JavaFX 애플리케이션을 위한 최종 실행 명령어 '공식'은 다음과 같습니다.

Bash

java --module-path [SDK 경로] --add-modules [모듈 목록] --add-exports [권한] -jar [내 앱.jar]

'자바의 신' 예제를 실행할 때 이 공식에 맞춰 사용했던 최종 명령어는 아래와 같습니다.

Bash

java --module-path javafx-sdk-17.0.15/lib --add-modules javafx.controls,javafx.fxml,javafx.web --add-exports javafx.graphics/com.sun.javafx.sg.prism=ALL-UNNAMED -jar godofjava-230902.jar

이제 이 명령어로 여러분의 JavaFX 애플리케이션도 시원하게 실행될 것입니다.

마치며

JavaFX 배포 과정이 예전보다 복잡해진 것은 사실입니다. 하지만 그 배경에 있는 '모듈 시스템'의 원리를 이해하면, 더 이상 에러 메시지 앞에서 당황하지 않고 문제를 해결해 나갈 수 있습니다. 이 가이드가 여러분의 성공적인 애플리케이션 배포에 도움이 되기를 바랍니다.

참고 자료

Stack Overflow: How to solve "Graphics Device initialization failed..." when running a JavaFX Jar file