[JAVA] Embedded Tomcat 기동 실패 원인 분석

Spring Boot에서 Embedded Tomcat이 기동되지 않는 문제는 생각보다 다양한 원인에서 발생합니다. 단순 설정 실수부터 클래스 충돌까지 범위가 넓기 때문에, 증상만 보고 접근하면 오히려 시간을 더 쓰게 됩니다. 실제로 자주 마주치는 실패 패턴을 기준으로 원인을 정리해보겠습니다.

Embedded Tomcat 기동 실패, 어디서부터 봐야 하는가

Embedded Tomcat 기동 실패는 대부분 애플리케이션 컨텍스트 초기화 단계에서 발생합니다. 즉, 서버 문제가 아니라 Spring Bean 생성 과정에서 이미 문제가 터진 상태인 경우가 많습니다. 로그를 보면 Tomcat 에러처럼 보이지만 실제 원인은 내부 Bean 초기화 실패인 경우가 흔합니다.

그래서 접근 순서는 단순합니다. Tomcat 로그가 아니라, 그 위에 있는 Caused by 체인을 끝까지 보는 것이 포인트입니다.

 

가장 흔한 원인 1: Bean 생성 실패

실무에서 가장 많이 보는 케이스입니다. 특정 Bean이 생성되지 않으면 Embedded Tomcat 자체가 올라오지 않습니다.

대표적인 예

Caused by: org.springframework.beans.factory.BeanCreationException

이 경우는 Tomcat 문제가 아니라 Bean 초기화 실패입니다. 주로 아래 상황에서 발생합니다.

- @Autowired 대상 Bean이 없는 경우
- 순환 참조 (circular dependency)
- 생성자 주입 시 의존성 누락
- @Configuration 설정 오류

처음 보면 Tomcat이 죽은 것처럼 보이지만, 실제로는 컨텍스트가 올라가지 못한 상태입니다.

 

가장 흔한 원인 2: 포트 충돌

의외로 단순하지만 자주 놓치는 부분입니다. 이미 동일 포트를 사용하는 프로세스가 있으면 Tomcat이 기동되지 않습니다.

확인 방법

lsof -i :8080

이미 사용 중이라면 프로세스를 종료하거나 포트를 변경하면 됩니다.

이 경우는 로그가 비교적 명확하게 나오기 때문에 빠르게 해결되는 편입니다.

 

가장 흔한 원인 3: 라이브러리 충돌 (javax vs jakarta)

Spring Boot 3.x 이상으로 올라가면서 많이 발생하는 문제입니다. javax.servlet과 jakarta.servlet이 섞이면 Tomcat이 정상적으로 초기화되지 않습니다.

특히 오래된 라이브러리를 그대로 가져온 경우에 자주 보입니다.

문제 상황 예

ClassNotFoundException: javax.servlet.Filter

Spring Boot 3부터는 jakarta.servlet을 사용합니다. 이 부분이 섞이면 기동 자체가 실패합니다.

이 경우는 의존성 트리를 확인해서 javax 관련 라이브러리를 제거하는 것이 필요합니다.

 

가장 흔한 원인 4: 설정 파일 오류

application.yml 또는 application.properties 설정 오류도 초기화 실패의 원인이 됩니다.

특히 아래와 같은 케이스에서 자주 발생합니다.

- 잘못된 datasource 설정
- profile 분기 오류
- 환경 변수 누락

이 경우는 Bean 생성 실패로 이어지기 때문에 앞에서 본 BeanCreationException과 함께 나타나는 경우가 많습니다.

 

가장 흔한 원인 5: 순환 참조 (Circular Dependency)

Spring Boot 2.6 이후부터는 기본적으로 순환 참조를 허용하지 않습니다. 이 설정 때문에 기존 코드가 갑자기 기동 실패하는 경우가 있습니다.

문제 예시

A -> B -> A

이 구조는 이전에는 동작하던 경우도 있지만, 최근 버전에서는 바로 실패합니다.

해결 방법은 구조를 분리하거나 인터페이스 레이어를 도입하는 방식이 일반적입니다.

 

디버깅 접근 방법 정리

이 문제를 빠르게 해결하려면 접근 순서를 정해두는 것이 좋습니다.

1. 로그에서 가장 아래 Caused by 확인
2. BeanCreationException 여부 확인
3. 포트 충돌 여부 확인
4. 의존성 충돌 여부 확인
5. 설정 파일 검증

특히 로그를 위에서부터 읽는 것이 아니라, 가장 아래부터 역으로 올라가는 방식이 훨씬 빠릅니다.

 

마무리

Embedded Tomcat 기동 실패는 Tomcat 자체 문제라기보다 Spring 초기화 실패로 보는 것이 더 정확합니다. 원인을 좁히는 기준만 명확히 잡아두면 디버깅 시간은 크게 줄어듭니다.

정리하면, Tomcat 에러 메시지에 집중하기보다 Bean 초기화 과정과 의존성 상태를 먼저 확인하는 접근이 효과적입니다.