갑자기 멈춘 스프링 서버 ContextLoaderListener 오류 파헤치기

24 April 2018

Update: 14 November 2025

어제 저녁 마지막 커밋까지 완벽하게 동작하던 프로젝트가 오늘 아침, 마치 약속이라도 한 듯 차가운 오류 메시지를 뿜어내며 시작조차 거부하는 상황. 모든 자바 웹 개발자라면 한 번쯤은 심장이 덜컥 내려앉는 이 경험을 해보셨을 겁니다. 그리고 그 중심에는 악명 높은 java.lang.IllegalStateException: Error configuring application listener of class org.springframework.web.context.ContextLoaderListener가 자리 잡고 있을 때가 많습니다. 이 오류는 단순한 오타나 논리적 버그가 아닙니다. 우리가 만든 애플리케이션이라는 건물이 기초 공사 단계에서부터 실패했음을 알리는, 매우 근본적인 문제의 신호입니다.

마치 자동차의 엔진 제어 장치(ECU)가 부팅에 실패하여 시동 자체가 걸리지 않는 것과 같습니다. 이 상황에서 운전자는 액셀을 밟거나 핸들을 돌리는 등의 행위는 아무 의미가 없음을 직감합니다. 마찬가지로, '애플리케이션 리스너 설정 오류'는 스프링 프레임워크의 심장인 IoC 컨테이너가 태동조차 하지 못했다는 의미이기에, 이후의 어떤 컨트롤러나 서비스도 호출될 수 없는 완전한 '먹통' 상태를 만듭니다. 문제는 이 오류 메시지가 "엔진 고장"이라고만 알려줄 뿐, 고장의 원인이 낡은 점화 플러그 때문인지, 연료 공급 라인이 막혔는지, 혹은 ECU 자체의 결함인지는 알려주지 않는다는 점입니다.

이 글은 풀스택 개발자로서 수없이 이 미스터리한 오류와 씨름하며 축적한 경험과 해결 전략을 집대성한 결과물입니다. 우리는 이 '리스너 설정 오류'라는 증상 뒤에 숨어있는 진짜 범인들, 즉 의존성 지옥의 망령부터 IDE의 배신, 설정 파일의 사소한 실수에 이르기까지 모든 가능성을 체계적으로 추적할 것입니다. 더 이상 어둠 속에서 헤매지 마십시오. 이 글을 나침반 삼아 문제의 근원을 정확히 진단하고, 여러분의 소중한 시간을 되찾으시길 바랍니다.

이 글의 목표: 단순한 해결책 나열을 넘어, ContextLoaderListener 초기화 실패의 근본 원인을 이해하고, 어떤 상황에서도 적용할 수 있는 체계적인 디버깅 전략을 제시합니다.

오류의 심장부: ServletContextListener와 스프링의 만남

효과적인 문제 해결은 문제의 본질을 꿰뚫어 보는 것에서 시작됩니다. 우리가 마주한 오류의 핵심에는 '애플리케이션 리스너', 더 정확히는 자바 서블릿 명세(Java Servlet Specification)에 정의된 javax.servlet.ServletContextListener 인터페이스가 있습니다. 이것은 단순한 클래스가 아니라, 웹 애플리케이션의 탄생과 죽음, 즉 생명주기(Life Cycle)의 가장 중요한 순간을 감지하고 개입할 수 있는 '관찰자'입니다.

톰캣(Tomcat), 제티(Jetty)와 같은 서블릿 컨테이너는 웹 애플리케이션을 배포(deploy)하고 시작할 때, 약속된 순서에 따라 이벤트를 발생시킵니다. ServletContextListener는 바로 이 두 가지 결정적인 이벤트를 수신합니다.

contextInitialized(ServletContextEvent sce): 웹 애플리케이션이 메모리에 로드되고 초기화될 때, 컨테이너에 의해 단 한 번 호출됩니다. 이 메소드가 바로 애플리케이션의 '창세기'에 해당합니다. 데이터베이스 커넥션 풀 생성, 설정 파일 로딩, 백그라운드 스케줄러 시작 등 애플리케이션 전역에서 사용될 공용 리소스를 준비하기에 가장 이상적인 시점입니다.
contextDestroyed(ServletContextEvent sce): 웹 애플리케이션이 종료되거나 서버에서 언로드(undeploy)될 때, 마찬가지로 단 한 번 호출됩니다. 이 메소드는 contextInitialized에서 생성했던 모든 리소스를 깨끗하게 정리하고 반환하는 '종말'의 역할을 수행하여 메모리 누수나 리소스 고갈을 방지합니다.

그렇다면 이것이 스프링 프레임워크와 무슨 관련이 있을까요? 바로 스프링 웹 애플리케이션의 핵심 부트스트래핑(bootstrapping)을 담당하는 org.springframework.web.context.ContextLoaderListener가 이 ServletContextListener의 대표적인 구현체이기 때문입니다. 개발자가 web.xml에 이 리스너를 등록하면, 서블릿 컨테이너는 애플리케이션 시작 시점에 ContextLoaderListener의 contextInitialized 메소드를 호출해줍니다. 그리고 바로 이 순간, 마법 같은 일이 벌어집니다.

ContextLoaderListener의 가장 중요한 임무는 스프링의 핵심인 루트 웹 애플리케이션 컨텍스트(Root Web ApplicationContext), 즉 IoC 컨테이너를 생성하고 초기화하는 것입니다. 이 과정에서 contextConfigLocation 파라미터로 지정된 설정 파일(예: applicationContext.xml, Java-based @Configuration 클래스)을 읽어들여, 그 안에 정의된 모든 빈(Bean)들을 인스턴스화하고, 의존성 주입(DI)을 완료하며, AOP 프록시를 적용하는 등 애플리케이션이 동작하는 데 필요한 모든 준비를 마칩니다. Spring Framework Documentation

따라서 Error configuring application listener of class ... ContextLoaderListener라는 메시지는 이 모든 과정이 실패했음을 의미합니다. 스프링 컨테이너라는 운영체제가 부팅조차 되지 않았으니, 그 위에서 동작해야 할 컨트롤러, 서비스, 리포지토리 등의 애플리케이션은 존재하지 않는 것과 같습니다. 이제 이 치명적인 오류가 왜 발생하는지, 그 근본적인 원인들을 하나씩 추적해 보겠습니다.

체계적인 원인 추적: 5가지 핵심 점검 포인트

하나의 증상 뒤에는 여러 원인이 복합적으로 얽혀있는 경우가 많습니다. 경험상, 이 오류의 원인은 크게 5가지 카테고리로 분류할 수 있습니다. 가장 빈번하게 발생하는 문제부터 순서대로, 각 상황에 맞는 구체적인 진단 기법과 해결 전략을 상세히 제시합니다.

1. 의존성 지옥(Dependency Hell)의 망령: 버전 충돌과 전이 의존성

현대 자바 개발에서 Maven이나 Gradle 같은 의존성 관리 도구는 축복이자 저주입니다. 편리하게 라이브러리를 추가할 수 있지만, 프로젝트 규모가 커질수록 보이지 않는 '전이 의존성(transitive dependency)' 문제가 발생할 확률이 기하급수적으로 높아집니다. 이것이 ContextLoaderListener 오류의 가장 흔한 주범입니다.

예를 들어, 우리 프로젝트는 spring-webmvc:5.3.20을 사용하도록 `pom.xml`에 명시했습니다. 자연스럽게 `spring-core`도 같은 5.3.20 버전으로 포함됩니다. 그런데 최근 데이터 처리를 위해 새로 추가한 cool-data-library:2.1.0이라는 라이브러리가 내부적으로 아주 오래된 spring-core:4.1.5.RELEASE를 필요로 한다고 가정해봅시다. 이 순간 '의존성 충돌'이 발생합니다.

Maven은 의존성 그래프를 해석하여 클래스패스에 단 하나의 spring-core 버전만 포함시켜야 합니다. 대부분의 경우, 더 가까운 의존성(프로젝트에 직접 명시한 5.3.20)을 선택하지만, 이 선택 과정이 꼬이거나, cool-data-library가 구버전의 특정 API(5.x 버전에서는 사라졌거나 변경된)에 강하게 의존하고 있다면, 런타임에 ClassNotFoundException, NoSuchMethodError, NoClassDefFoundError와 같은 예외가 발생하며 스프링 컨텍스트 초기화가 실패하게 됩니다.

진단 방법: `mvn dependency:tree`로 의존성 계보 파헤치기

문제 해결의 첫걸음은 현재 내 프로젝트에 어떤 라이브러리들이, 어떤 경로를 통해, 어떤 버전으로 포함되어 있는지 정확히 파악하는 것입니다. 프로젝트의 루트 디렉토리에서 아래 명령어를 실행하면 모든 비밀이 드러납니다.


# Maven 프로젝트의 경우
mvn dependency:tree

# Gradle 프로젝트의 경우
gradle dependencies

이 명령어는 프로젝트의 모든 의존성을 텍스트 기반의 트리 형태로 출력해줍니다. 버전 충돌이 발생한 부분을 찾아내기에 이보다 더 좋은 도구는 없습니다.


[INFO] com.mycompany:my-webapp:war:1.0.0-SNAPSHOT
[INFO] +- org.springframework:spring-webmvc:jar:5.3.20.RELEASE:compile
[INFO] |  +- org.springframework:spring-aop:jar:5.3.20.RELEASE:compile
[INFO] |  +- org.springframework:spring-beans:jar:5.3.20.RELEASE:compile
[INFO] |  +- org.springframework:spring-context:jar:5.3.20.RELEASE:compile
[INFO] |  +- org.springframework:spring-core:jar:5.3.20.RELEASE:compile  <-- 최종 선택된 버전
[INFO] |  |  \- org.springframework:spring-jcl:jar:5.3.20.RELEASE:compile
[INFO] |  \- org.springframework:spring-web:jar:5.3.20.RELEASE:compile
[INFO] \- com.mycompany:cool-data-library:jar:2.1.0:compile
[INFO]    \- org.apache.httpcomponents:httpclient:jar:4.5.13:compile
[INFO]    \- org.springframework:spring-core:jar:4.1.5.RELEASE:compile (omitted for conflict with 5.3.20.RELEASE) <-- 충돌로 인해 제외됨

위 예시를 보면 `cool-data-library`가 가져온 spring-core:4.1.5.RELEASE가 우리 프로젝트의 5.3.20.RELEASE 버전과의 충돌로 인해 클래스패스에서 제외(omitted)되었음을 명확히 알 수 있습니다. 대부분은 이것이 올바른 해결책이지만, 만약 이로 인해 문제가 발생한다면 우리는 적극적으로 개입해야 합니다.

해결 전략: `<dependencyManagement>`와 `<exclusions>`의 지혜로운 사용

의존성 충돌을 해결하는 방법은 크게 두 가지, 사전 예방적인 접근과 사후 처리적인 접근이 있습니다.

전략	설명	장점	단점
`<dependencyManagement>` (사전 예방)	프로젝트 전체에서 사용할 라이브러리의 버전을 중앙에서 명시적으로 선언합니다. 일종의 '버전 통제 센터' 역할을 합니다.	일관성 유지, 버전 충돌 원천 방지, 하위 모듈까지 버전 강제.	초기 설정이 다소 복잡하게 느껴질 수 있음.
`<exclusions>` (사후 처리)	특정 라이브러리가 끌고 오는 문제의 전이 의존성을 개별적으로 제외시킵니다.	문제가 되는 부분만 빠르게 조치 가능, 직관적임.	프로젝트가 커지면 관리가 어려워지고, 여러 곳에서 동일한 exclusion을 반복해야 할 수 있음.

1. <dependencyManagement>를 이용한 버전 중앙 관리 (강력 추천)

pom.xml의 최상단에 이 섹션을 추가하여 "우리 프로젝트에서는 스프링 관련 라이브러리는 무조건 5.3.20 버전을 사용한다"고 선언하는 것입니다. Spring에서는 관련된 라이브러리들의 버전 조합을 미리 정의해놓은 BOM(Bill of Materials) 파일을 제공하므로 이를 사용하는 것이 가장 좋습니다.


<properties>
    <org.springframework.version>5.3.20.RELEASE</org.springframework.version>
</properties>

<dependencyManagement>
    <dependencies>
        <!-- Spring Framework BOM을 import하여 관련 라이브러리 버전을 일괄 관리 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-framework-bom</artifactId>
            <version>${org.springframework.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- 이제 개별 의존성에는 버전을 명시할 필요가 없습니다. dependencyManagement에서 관리됩니다. -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-webmvc</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
    </dependency>
    ...
</dependencies>

2. <exclusions>를 이용한 문제 의존성 제거

특정 라이브러리가 가져오는 의존성만 핀포인트로 제거하고 싶을 때 사용합니다.


<dependency>
    <groupId>com.mycompany</groupId>
    <artifactId>cool-data-library</artifactId>
    <version>2.1.0</version>
    <exclusions>
        <!-- cool-data-library가 내부적으로 사용하는 spring-core를 제외시킨다. -->
        <!-- 우리 프로젝트의 상위 버전 spring-core가 대신 사용될 것이다. -->
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>

2. 설정 파일의 배신: 오타 하나가 모든 것을 무너뜨린다

가장 기본적인 부분이지만, 급하게 작업하다 보면 의외로 자주 발생하는 실수입니다. 클래스 이름의 오타, 파일 경로의 오류 등은 서블릿 컨테이너가 ContextLoaderListener를 찾거나 설정 파일을 읽는 것 자체를 불가능하게 만듭니다.

진단 및 해결 방법: 돋보기를 들고 설정 파일을 정밀 검사하라

web.xml 파일 검사:

<listener> 태그 내부의 <listener-class>에 기술된 클래스의 전체 경로가 정확한지 확인하세요. (예: org.springframework.web.context.ContextLoaderListener)
<context-param>의 <param-name>이 contextConfigLocation으로 정확히 기재되었는지 확인하세요.
<param-value>에 명시된 스프링 설정 파일의 경로가 실제 파일 위치와 일치하는지 확인하세요. classpath: 접두사는 컴파일된 클래스 파일들이 위치하는 경로(주로 /WEB-INF/classes, Maven/Gradle 프로젝트에서는 src/main/resources)를 의미합니다.


<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">

    <!-- 1. 스프링 설정 파일 위치 지정 (경로와 파일명 확인!) -->
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:spring/root-context.xml</param-value>
    </context-param>

    <!-- 2. 리스너 클래스 전체 경로 확인! -->
    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <!-- ... DispatcherServlet 등 기타 설정 ... -->
</web-app>

스프링 XML 설정 파일 (root-context.xml 등) 검사:
- XML 네임스페이스 선언(xmlns)이 올바른지, 스키마 위치(xsi:schemaLocation)가 유효한지 확인합니다. IDE는 보통 이 부분에 오류가 있으면 즉시 경고를 표시해줍니다.
- <bean> 태그의 class 속성에 지정된 클래스 경로에 오타는 없는지 확인합니다.
- <context:component-scan>의 base-package가 스캔하고자 하는 패키지를 정확히 가리키고 있는지 확인합니다.
IDE의 자동 완성 기능과 유효성 검사 기능을 최대한 활용하여 실수를 줄이는 것이 중요합니다.

3. 개발 도구의 착각: IDE와 빌드 도구의 불협화음

이것은 특히 베테랑 개발자도 종종 함정에 빠지는 매우 교묘한 문제입니다. Eclipse, IntelliJ IDEA와 같은 통합 개발 환경(IDE)은 Maven의 `pom.xml`이나 Gradle의 `build.gradle` 파일과는 별개로, 자신만의 프로젝트 설정 메타데이터 파일(예: Eclipse의 .project, .classpath 파일, IntelliJ의 .idea 디렉토리와 .iml 파일)을 유지합니다.

개발자가 `pom.xml`에 새로운 의존성을 추가하거나 버전을 변경했을 때, 대부분의 경우 IDE는 이를 감지하고 자동으로 자신의 설정에 반영합니다. 하지만 때때로 이 동기화 과정이 누락되거나 실패하는 경우가 발생합니다. 개발자의 눈에는 `pom.xml`이 완벽해 보이지만, 정작 애플리케이션을 실행하는 IDE는 낡고 부정확한 클래스패스 정보를 가지고 있는 것입니다. 그 결과, IDE는 당연히 있어야 할 클래스(예: `ContextLoaderListener` 자체 또는 그것이 의존하는 다른 클래스)를 찾지 못하고 오류를 발생시킵니다.

진단 및 해결 방법: Maven/Gradle 프로젝트 강제 동기화

의존성이나 설정에 아무런 문제가 없어 보이는데도 오류가 지속된다면, 가장 먼저 시도해야 할 조치입니다. 이는 IDE에게 빌드 스크립트(`pom.xml`)를 처음부터 다시 정독하고 프로젝트 설정을 완전히 새로고침하라고 명령하는 것과 같습니다.

IntelliJ IDEA의 경우:
1. 화면 우측의 Maven 또는 Gradle 탭을 엽니다.
2. 탭 상단에 있는 원형 화살표 모양의 'Reload All Maven Projects' 또는 'Reload All Gradle Projects' 버튼을 클릭합니다.
3. 또는, `pom.xml`이나 `build.gradle` 파일을 에디터에서 열고 마우스 오른쪽 버튼을 클릭한 후, `Maven` > `Reload project`를 선택해도 됩니다.
IntelliJ IDEA의 Maven 도구 창에서 'Reload' 버튼을 눌러 프로젝트를 강제로 동기화할 수 있습니다.
Eclipse의 경우:
1. 'Project Explorer' 뷰에서 해당 프로젝트를 마우스 오른쪽 버튼으로 클릭합니다.
2. 컨텍스트 메뉴에서 `Maven` > `Update Project...`를 선택합니다.
3. 나타나는 대화 상자에서 해당 프로젝트가 체크되어 있는지 확인하고, "Force Update of Snapshots/Releases" 옵션을 체크한 후 `OK` 버튼을 클릭합니다.

이 간단한 조치만으로도 해결되는 경우가 놀라울 정도로 많습니다. 마치 컴퓨터가 이상할 때 재부팅하는 것과 같은 효과를 줍니다.

4. 오염된 로컬 저장소: 보이지 않는 함정 `.m2` 폴더

Maven은 원격 저장소(예: Maven Central)에서 다운로드한 모든 라이브러리 파일(.jar, .pom 등)을 로컬 컴퓨터의 특정 폴더에 캐싱하여 재사용합니다. 이 폴더가 바로 사용자의 홈 디렉토리 아래에 있는 .m2/repository 입니다. Gradle도 비슷한 자체 캐시 폴더(.gradle/caches)를 사용합니다.

문제는 이 로컬 캐시가 때때로 '오염'될 수 있다는 것입니다. 예를 들어, 라이브러리를 다운로드하는 도중 네트워크 연결이 불안정하여 파일이 중간에 끊기거나, 빌드 프로세스가 강제 종료되면서 파일이 불완전하게 저장될 수 있습니다. 이렇게 되면 .jar 파일이 존재하기는 하지만, 실제로는 깨진(corrupted) 파일입니다. 애플리케이션 시작 시 클래스로더가 이 손상된 jar 파일을 읽으려고 시도하면 java.util.zip.ZipException: error in opening zip file 과 같은 예상치 못한 오류가 발생하며, 결국 ContextLoaderListener 초기화 실패로 이어질 수 있습니다.

진단 및 해결 방법: 로컬 저장소 정화 작업

이 문제는 눈에 잘 띄지 않기 때문에 진단이 어렵지만, 해결 방법은 의외로 간단합니다.

문제 의존성 특정 (선택 사항): 에러 로그나 `mvn dependency:tree`를 통해 최근에 추가했거나 문제가 될 만한 라이브러리를 추측해봅니다.
해당 라이브러리 캐시 폴더 삭제: .m2/repository 디렉토리로 이동하여 문제가 의심되는 라이브러리의 폴더를 통째로 삭제합니다. 예를 들어, spring-core가 의심된다면 .m2/repository/org/springframework/spring-core 폴더를 삭제합니다.
프로젝트 재빌드: 그 후 IDE에서 Maven 프로젝트를 업데이트하거나, 터미널에서 mvn clean install -U 명령을 실행합니다. -U 옵션은 스냅샷 의존성을 강제로 업데이트하도록 하여 효과를 높입니다. Maven은 로컬 캐시에 해당 라이브러리가 없어진 것을 확인하고 원격 저장소에서 깨끗한 파일로 다시 다운로드할 것입니다.
최후의 수단 (전체 캐시 삭제): 어떤 라이브러리가 문제인지 전혀 감이 오지 않는다면, .m2/repository 폴더 전체를 삭제하거나 이름을 바꾸는(예: repository_bak) 과감한 방법을 시도해볼 수 있습니다. 이 방법을 사용하면 다음 빌드 시 모든 프로젝트의 모든 의존성을 처음부터 다시 다운로드해야 하므로 시간이 매우 오래 걸릴 수 있지만, 캐시 오염 문제를 확실하게 해결할 수 있습니다.

주의: 로컬 저장소를 삭제하기 전에 중요한 사내 라이브러리나 직접 빌드하여 설치한 라이브러리가 없는지 확인하세요. 삭제 시 해당 라이브러리들도 다시 설치해야 합니다.

5. 환경의 벽: JDK와 서블릿 컨테이너 버전의 불일치

개발 환경(내 PC)과 실행 환경(테스트/운영 서버)의 미묘한 차이 역시 오류의 원인이 될 수 있습니다. 특히 자바 버전과 서블릿 컨테이너 버전은 매우 중요합니다.

JDK 버전 불일치

예를 들어, 프로젝트는 최신 JDK 17로 컴파일되었는데, 운영 서버의 톰캣은 낡은 JDK 8 환경에서 실행되고 있다고 가정해봅시다. 이 경우, 톰캣이 애플리케이션 클래스를 로드하는 순간 java.lang.UnsupportedClassVersionError가 발생합니다. 이 오류는 더 높은 버전의 자바 컴파일러로 생성된 클래스 파일을 낮은 버전의 JVM이 실행하려고 할 때 발생하며, 리스너 클래스 로딩 단계에서 이 문제가 터지면 초기화 실패로 이어집니다.

해결 방법: `pom.xml`의 `maven-compiler-plugin` 설정을 통해 프로젝트의 소스 및 타겟 자바 버전을 명시하고, 이것이 실제 배포될 서버의 JDK 버전과 호환되는지 반드시 확인해야 합니다.


<properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
</properties>

<!-- 또는 플러그인 설정을 통해 명시적으로 지정 -->
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
                <source>11</source>
                <target>11</target>
            </configuration>
        </plugin>
    </plugins>
</build>

서블릿 API 버전 불일치: `javax` vs `jakarta`

이것은 최근 몇 년간 많은 개발자들을 혼란에 빠뜨린 중요한 변화입니다. Java EE가 Eclipse 재단으로 이관되면서 Jakarta EE로 이름이 바뀌었고, 이 과정에서 핵심 API들의 패키지 이름이 javax.* 에서 jakarta.* 로 변경되었습니다.

이 변화는 서블릿 컨테이너에 직접적인 영향을 미쳤습니다.

서블릿 컨테이너	지원하는 서블릿 명세	패키지 네임스페이스	필요한 Maven 의존성
Tomcat 9.x, Jetty 10.x 이하	Servlet 4.0 이하	`javax.servlet.*`	`<groupId>javax.servlet</groupId><artifactId>javax.servlet-api</artifactId>`
Tomcat 10.x, Jetty 11.x 이상	Servlet 5.0 이상	`jakarta.servlet.*`	`<groupId>jakarta.servlet</groupId><artifactId>jakarta.servlet-api</artifactId>`

만약 톰캣 10 서버에 애플리케이션을 배포하면서, `pom.xml`에는 여전히 낡은 javax.servlet-api 의존성을 포함하고 있다면 어떻게 될까요? 톰캣 10은 jakarta.servlet.ServletContextListener를 구현한 클래스를 찾으려 하지만, 우리 프로젝트는 javax.servlet.ServletContextListener를 구현한 ContextLoaderListener를 가지고 있습니다. 결과적으로 톰캣은 리스너를 인식하지 못하거나 클래스를 찾지 못해 `ClassNotFoundException`과 함께 구동에 실패합니다. 반대의 경우도 마찬가지입니다. 실행 환경과 프로젝트의 서블릿 API 의존성 버전은 반드시 일치해야 합니다.

현대적 접근: Spring Boot 환경에서는 무엇이 다른가?

지금까지의 논의는 주로 web.xml을 사용하는 전통적인 WAR 배포 방식에 초점을 맞추었습니다. 하지만 현대의 많은 프로젝트는 내장 서블릿 컨테이너를 사용하여 `main` 메소드로 간단히 실행하는 스프링 부트(Spring Boot)를 기반으로 합니다. 이 환경에서는 `web.xml`이 없는데, 과연 '리스너 설정 오류'와 같은 문제가 발생할까요?

답은 '그렇다'입니다. 형태는 다르지만 본질은 같습니다. 스프링 부트에서도 애플리케이션 구동이 실패하는 경우는 비일비재하며, 그 근본 원인은 앞서 다룬 5가지 포인트와 크게 다르지 않습니다.

스프링 부트에서는 @SpringBootApplication 어노테이션이 붙은 클래스의 `main` 메소드가 실행되면, 자동 설정(Auto-configuration) 메커니즘이 동작하여 필요한 모든 구성을 마법처럼 수행합니다. 이 과정에서 발생하는 구동 실패는 주로 다음과 같은 원인에 기인합니다.

의존성 충돌: 스프링 부트에서도 의존성 충돌은 여전히 구동 실패의 가장 큰 원인입니다. 스프링 부트는 spring-boot-starter-parent POM을 통해 검증된 라이브러리 버전들을 <dependencyManagement>에 정의하여 제공하지만, 개발자가 임의로 특정 라이브러리의 버전을 오버라이드하거나, 부트의 버전과 호환되지 않는 라이브러리를 추가할 때 문제가 발생할 수 있습니다. `mvn dependency:tree`를 통한 분석은 여기서도 똑같이 유효합니다.
설정(Configuration) 오류: web.xml이나 XML 설정 파일의 역할은 @Configuration 어노테이션이 붙은 자바 클래스와 application.properties (또는 .yml) 파일이 대신합니다. 예를 들어, @Configuration 클래스 내의 @Bean 메소드에서 순환 참조가 발생하거나, application.properties에 정의된 데이터베이스 접속 정보(URL, username, password)가 틀려서 DataSource 빈 생성에 실패하면, 전체 애플리케이션 컨텍스트 로딩이 중단되며 구동에 실패합니다.
컴포넌트 스캔(Component Scan) 문제: @SpringBootApplication은 기본적으로 해당 어노테이션이 붙은 클래스가 위치한 패키지와 그 하위 패키지만을 스캔하여 빈으로 등록합니다. 만약 스캔이 필요한 @Service, @Repository, @Configuration 클래스가 스캔 범위 밖에 있다면, 의존성 주입(DI)에 실패하여 애플리케이션이 시작되지 못합니다.

다행히도 스프링 부트는 애플리케이션 구동 실패 시 매우 상세하고 친절한 분석 리포트를 콘솔에 출력해줍니다. 오류 로그의 마지막 부분에 있는 `--- FAILED TO START ---` 블록을 주의 깊게 읽어보세요. 대부분 '`Description`' 부분에 실패의 원인이 명확하게 기술되어 있고, '`Action`' 부분에는 문제를 해결하기 위한 구체적인 제안(예: "Consider defining a bean of type '...' in your configuration.")이 포함되어 있습니다. 이것이 문제 해결의 가장 중요한 단서입니다.

결론: 증상 너머의 근본 원인을 향한 탐정의 자세

Error configuring application listener라는 오류 메시지는 개발자에게 보내는 경고등이자, 동시에 우리의 애플리케이션 구조를 더 깊이 이해할 수 있는 기회입니다. 이 문제는 단순한 코딩 실수가 아니라, 프로젝트의 뼈대를 이루는 의존성, 설정, 환경이라는 세 가지 축 어딘가에 균열이 생겼다는 강력한 증거입니다.

이 혼란스러운 문제를 마주했을 때, 당황하며 무작위로 설정을 바꾸는 대신 다음과 같은 체계적인 접근 방식을 따르는 것이 중요합니다. 이것은 당신을 헤매지 않는 길로 안내할 것입니다.

Application Listener 오류 해결을 위한 최종 체크리스트

로그를 탐정처럼 읽어라: 오류 메시지 한 줄만 보지 마십시오. 전체 스택 트레이스(stack trace)를 위에서부터 꼼꼼히 읽어 내려가며 `Caused by:` 구문을 찾으세요. 진짜 범인에 대한 결정적인 단서는 대부분 그곳에 숨어있습니다. `ClassNotFoundException`, `NoSuchMethodError`, `BeanCreationException` 등 구체적인 예외 이름이 무엇인지 확인하는 것이 첫걸음입니다.
의존성을 가장 먼저 의심하라: 최근에 새로운 라이브러리를 추가했거나 기존 라이브러리의 버전을 변경했습니까? 그렇다면 거의 90% 확률로 의존성 문제가 원인입니다. 주저 없이 터미널을 열고 mvn dependency:tree를 실행하여 의존성 구조를 분석하고 버전 충돌 지점을 색출하십시오.
IDE와 빌드 도구를 동기화하라: 의존성에 명백한 문제가 보이지 않는다면, 가장 간단하고 효과적인 처방인 'Maven/Gradle Project Reload'를 시도하여 IDE와 빌드 스크립트의 상태를 완벽하게 일치시키십시오.
설정 파일을 다시 심문하라: web.xml, root-context.xml, application.properties 등 모든 설정 파일을 열어 클래스 경로, 파일 경로, 프로퍼티 키 등에 오타나 논리적 오류가 없는지 다시 한번 확인하십시오.
환경의 알리바이를 확인하라: 로컬 개발 환경, 테스트 서버, 운영 서버의 JDK 버전과 서블릿 컨테이너(Tomcat 등) 버전이 프로젝트 설정(pom.xml의 자바 버전, 서블릿 API 의존성)과 정확히 일치하는지 점검하십시오. 특히 javax와 jakarta의 차이를 명심하십시오.

이처럼 체계적인 진단 과정을 거치면, 안개 속에 가려져 있던 문제의 실마리가 하나씩 풀리기 시작할 것입니다. 이 글에서 다룬 다양한 원인 분석과 해결 전략들이 여러분이 마주한 '리스너 설정 오류'라는 높은 벽을 넘어서고, 한 단계 더 성장하는 개발자가 되는 데 훌륭한 디딤돌이 되기를 진심으로 바랍니다.

ko Servlet API Spring Boot