리눅스에서 java.lang.NoClassDefFoundError: sun/awt/X11GraphicsEnvironment 에러가 발생할 경우

리눅스에서 java.lang.NoClassDefFoundError: sun/awt/X11GraphicsEnvironment 에러가 발생할 경우

시스템 프로퍼티 java.awt.headless를 true로 설정해주면 된다.
톰캣의 경우 catalina.sh 파일 제일 위에 CATALINA_OPTS=“-Djava.awt.headless=true” 를 추가한다.

ps -eaf | grep java 로 확인해보면 “-Djava.awt.headless=true가 추가되어있는 것을 확인할 수 있다.

위 메모의 옵션 값은 셸에서 따옴표까지 올바르게 작성해야 한다. 톰캣 시작 스크립트에 적용할 때는 다음처럼 기존 옵션을 유지한다.

CATALINA_OPTS="$CATALINA_OPTS -Djava.awt.headless=true"

headless 모드는 디스플레이 장치 없이 동작하는 서버에서 AWT의 화면 관련 기능을 사용하지 않도록 한다. 이미지를 읽거나 그리는 코드가 화면 창을 열 필요가 없는지 먼저 확인한다. 실제로 데스크톱 화면이 필요한 코드라면 이 옵션만으로 해결되지 않는다.

실행 중인 JVM에 옵션이 적용됐는지 시작 로그나 프로세스 인수를 확인하고, 오류가 계속되면 최초 원인 예외와 설치된 그래픽 라이브러리를 확인한다. 자바 실행 옵션은 운영 환경의 서비스 설정에서 관리하는 편이 시작 스크립트를 직접 수정하는 것보다 추적하기 쉽다.

발생 조건과 첫 진단

이 오류는 서버나 컨테이너에서 Java AWT가 그래픽 환경에 접근할 때 나타날 수 있다. 그러나 NoClassDefFoundError라는 이름만 보고 곧바로 “X 서버가 없어서”라고 결론 내리면 안 된다. 해당 클래스를 찾지 못했거나 초기화 과정에서 다른 오류가 먼저 발생한 경우처럼 원인이 다를 수 있다. 로그에서 이 메시지가 나온 첫 요청의 가장 안쪽 원인과 JVM 실행 옵션을 함께 확인한다.

java -version
# 실행 중인 JVM의 실제 인수 확인. PID는 해당 프로세스 번호로 바꾼다.
ps -p PID -o args=

이미지를 파일로 읽거나 생성하는 서비스라면 새 프로세스에서 java -Djava.awt.headless=true -jar app.jar로 같은 작업을 재현해 본다. headless 모드는 이미지 처리와 글꼴 연산처럼 화면이 없어도 가능한 기능은 유지하지만, 창을 띄우거나 키보드·마우스 입력을 받는 기능까지 제공하지 않는다. 옵션 적용 후 GraphicsEnvironment.isHeadless()가 true인지 작은 진단 코드로 확인할 수 있다.

import java.awt.GraphicsEnvironment;

public class HeadlessCheck {
    public static void main(String[] args) {
        System.out.println(GraphicsEnvironment.isHeadless());
    }
}

적용 후에도 실패할 때

true인데도 실패하면 첫 스택 트레이스의 Caused by를 다시 본다. 누락된 네이티브 라이브러리, 잘못된 JDK 런타임 구성, 글꼴·이미지 플러그인 문제는 headless 옵션 하나로 해결되지 않는다.
Tomcat에서 CATALINA_OPTS를 바꿨다면 실제 서비스를 다시 시작하고 실행 인수를 확인한다. 다른 Tomcat 인스턴스나 systemd 단위 파일을 수정했으면 결과가 달라지지 않는다.
애플리케이션이 실제로 창을 열어야 한다면 headless를 강제하는 대신 디스플레이 서버가 있는 환경에서 실행해야 한다. 화면 없는 배치 작업인지 데스크톱 프로그램인지 요구를 먼저 구분한다.
컨테이너에서만 재현된다면 호스트의 X 라이브러리 상태가 아니라 컨테이너 내부의 JDK와 라이브러리를 조사한다.

운영 설정을 바꿀 때는 재현 조건, 변경한 JVM 옵션, 재시작 시각, 재실행 결과를 함께 기록한다. 동일한 메시지가 사라졌더라도 이미지가 실제로 생성되고 파일 형식이 올바른지까지 확인해야 해결됐다고 판단할 수 있다.

Oracle의 headless AWT 설명과 NoClassDefFoundError API 문서를 참고한다.