springframework.web.filter.CharacterEncodingFiler cannot be cast to class jakarta.servlet.Filter

안녕하세요.
이렇게 에러 관련된 포스팅을 쓰다가 너무 많아 질까 걱정이네요.
거의 개인 노트가 되어가고 있습니다.

프로젝트 환경을 java 21로 업데이트를 해야합니다.
그러다 보니 이클립스 버전을 바꾸게 되고, 톰캣 버전을 바꾸게 되고, 그다음 스프링 버전까지 올려야 하는 상황입니다.

그러다 발생한 오류를 적어봅니다.

---

❗ CharacterEncodingFilter cannot be cast to class jakarta.servlet.Filter 오류 해결 가이드

---

📌 오류 메시지

springframework.web.filter.CharacterEncodingFilter cannot be cast to class jakarta.servlet.Filter

이 오류는 javax.servlet.Filter와 jakarta.servlet.Filter 간의 호환성 문제로 인해 발생합니다. 즉, Spring의 필터는 javax.servlet.Filter 기준으로 작성되었는데, 실행 환경은 jakarta.servlet.Filter만 인식할 때 발생합니다.

---

🧨 주요 원인(버전 변경시 조심하세요)

항목	설명
Spring 버전	Spring 5.x 이하는 javax.servlet.* 사용
Servlet 컨테이너	Tomcat 10 이상은 jakarta.servlet.* 요구
결과	Filter 클래스 간 타입 불일치로 인한 ClassCastException 발생

---

✅ 해결 방법

1. Spring 버전 업그레이드

Spring Framework 6.x 이상 또는 Spring Boot 3.x 이상으로 업그레이드하면 Jakarta EE 9 이상 호환됩니다.

➤ Spring Boot 예시

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.2.0</version>
</parent>

➤ Spring MVC 단독 예시

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-webmvc</artifactId>
  <version>6.1.6</version>
</dependency>

Spring 6부터는 jakarta.servlet을 기본으로 사용

---

2. 톰캣 9.x 사용 (Servlet 4.0)

• Spring 5.x 이하를 그대로 유지하고 싶다면 톰캣 9.x로 다운그레이드하면 호환됩니다.
• Tomcat 9은 javax.servlet 기반

---

3. 의존성 충돌 제거

➤ Maven에서 확인

mvn dependency:tree

• javax.servlet-api와 jakarta.servlet-api가 동시에 존재하지 않도록 설정
• 중복 제거 후 재빌드

---

🧪 부가 확인사항

• web.xml에서 filter-class는 jakarta.servlet.Filter 기준이어야 함
• Java 코드에서 import jakarta.servlet.Filter로 정확히 가져와야 함

---

✅ 요약

상황	조치
Spring 5.x + Tomcat 10.x	❌ 비호환 (오류 발생)
Spring 5.x + Tomcat 9.x	✅ 호환 가능
Spring 6.x + Tomcat 10.x	✅ 완전 호환
의존성 충돌 (javax + jakarta)	❌ 제거 필요

---

저는
스프링 버전 6, 자바 버전 21, 톰캣 버전 10.1로 새로운 프로젝트를 구성할 계횝입니다.
모두 화이팅!