[ 트러블 슈팅 ] The bean 'jwtFilter' could not be registered 에러 해결하기

Spring 프로젝트를 진행하다보면 다음과 같은 에러를 마주할 때가 있다.

The bean 'jwtFilter', defined in class path resource [org/example/expert/config/FilterConfig.class], could not be registered. A bean with that name has already been defined in file [/Users/t2023-m0071/IdeaProjects/spring-plus/build/classes/java/main/org/example/expert/config/JwtFilter.class] and overriding is disabled.

---

문제 상황

위 에러는 JwtFilter.class에서 이미 Bean으로 등록한 상태에서, FilterConfig.class에서도 동일한 이름으로 Bean을 등록하려고 시도하면서 발생한 문제이다.
Spring에서는 기본적으로 같은 이름의 Bean을 중복해서 등록할 수 없도록 설정되어 있기 때문에, 이 경우 충돌이 발생하게 된다.

---

문제 원인 분석

 Spring에서 Bean을 등록할 때 중복 등록 방지 때문에 발생한다.

• JwtFilter.class에서 이미 @Component 어노테이션을 사용해서 Bean으로 등록한 상태이다.
• 그러나 FilterConfig.class에서 같은 이름으로 Bean을 또 등록하려고 시도하면서 충돌이 발생했다.

---

해결 방법

중복으로 등록된 Bean 중 하나를 제거해야 한다.
이 경우에는 FilterConfig를 사용하는 목적이 명확하지 않다면, FilterConfig를 삭제하는 것이 적합하다.
실제로 FilterConfig.class를 삭제하고 application을 다시 실행했을 때 문제가 해결됐다.

---

해결 과정

• FilterConfig.class의 역할 확인
  • JwtFilter 외에 다른 필러를 관리하는 역할이 없다면 해당 클래스를 삭제해도 문제없다.
• FilterConfig.class 삭제
  • 프로젝트에서 FilterConfig.class 파일을 제거했다.
• application 재실행
  • 에러 없이 정상적으로 실행되는 것을 확인했다.

---

참고 코드

JwtFilter.class

@Slf4j
@RequiredArgsConstructor
public class JwtFilter implements Filter {

    private final JwtUtil jwtUtil;

    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
        Filter.super.init(filterConfig);
    }

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        HttpServletResponse httpResponse = (HttpServletResponse) response;

        String url = httpRequest.getRequestURI();

        if (url.startsWith("/auth")) {
            chain.doFilter(request, response);
            return;
        }

        String bearerJwt = httpRequest.getHeader("Authorization");

        if (bearerJwt == null) {
            // 토큰이 없는 경우 400을 반환합니다.
            httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "JWT 토큰이 필요합니다.");
            return;
        }

        String jwt = jwtUtil.substringToken(bearerJwt);

        try {
            // JWT 유효성 검사와 claims 추출
            Claims claims = jwtUtil.extractClaims(jwt);
            if (claims == null) {
                httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "잘못된 JWT 토큰입니다.");
                return;
            }

            UserRole userRole = UserRole.valueOf(claims.get("userRole", String.class));

            httpRequest.setAttribute("userId", Long.parseLong(claims.getSubject()));
            httpRequest.setAttribute("email", claims.get("email"));
            httpRequest.setAttribute("nickname", claims.get("nickname"));
            httpRequest.setAttribute("userRole", claims.get("userRole"));

            if (url.startsWith("/admin")) {
                // 관리자 권한이 없는 경우 403을 반환합니다.
                if (!UserRole.ADMIN.equals(userRole)) {
                    httpResponse.sendError(HttpServletResponse.SC_FORBIDDEN, "관리자 권한이 없습니다.");
                    return;
                }
                chain.doFilter(request, response);
                return;
            }

            chain.doFilter(request, response);
        } catch (SecurityException | MalformedJwtException e) {
            log.error("Invalid JWT signature, 유효하지 않는 JWT 서명 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "유효하지 않는 JWT 서명입니다.");
        } catch (ExpiredJwtException e) {
            log.error("Expired JWT token, 만료된 JWT token 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "만료된 JWT 토큰입니다.");
        } catch (UnsupportedJwtException e) {
            log.error("Unsupported JWT token, 지원되지 않는 JWT 토큰 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "지원되지 않는 JWT 토큰입니다.");
        } catch (Exception e) {
            log.error("Internal server error", e);
            httpResponse.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
        }
    }

    @Override
    public void destroy() {
        Filter.super.destroy();
    }
}

삭제된 FilterConfig.class

@Configuration
@RequiredArgsConstructor
public class FilterConfig {

    private final JwtUtil jwtUtil;

    @Bean
    public FilterRegistrationBean<JwtFilter> jwtFilter() {
        FilterRegistrationBean<JwtFilter> registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(new JwtFilter(jwtUtil));
        registrationBean.addUrlPatterns("/*"); // 필터를 적용할 URL 패턴을 지정합니다.

        return registrationBean;
    }
}

---

결론

Spring에서 동일한 이름의 Bean을 중복 등록하려고 하면 위와 같이 충돌이 발생할 수 있다.
이렇게 충돌이 발생하는 경우 다음과 같이 해결할 수 있다.

• Bean이 이미 등록되어 있는지 확인하기
• 같은 이름으로 Bean을 중복 등록하지 않도록 코드 설계를 개선하기
• 필요 없는 클래스를 제거하여 중복 문제를 해결하기