NestedServletException + IllegalArgumentException: Invalid URL encoding

Spring 웹 애플리케이션에서 요청 처리 중 다음과 같은 예외가 발생하는 경우가 있습니다.

---

에러 메시지

org.springframework.web.util.NestedServletException: Request processing failed;
nested exception is java.lang.IllegalArgumentException: Invalid URL encoding.

---

원인 분석

이 에러는 다음과 같은 상황에서 발생합니다:

핵심 원인

URL 쿼리 파라미터 또는 경로 내에 잘못된 인코딩 문자열이 포함되어 있음

예를 들어:

http://example.com/search?q=%E1%ZZ

위와 같이 %로 시작하지만 정상적인 16진수 2자리(hex)가 아닌 문자열이 포함될 경우, 디코딩 중 IllegalArgumentException이 발생합니다.

Spring의 처리 방식

• Spring은 HTTP 요청을 처리하면서 내부적으로 URL을 디코딩합니다.
• 이 과정에서 정상적이지 않은 인코딩 포맷이 있을 경우, IllegalArgumentException: Invalid URL encoding을 발생시키고,
  이를 NestedServletException으로 래핑하여 처리합니다.

---

해결 방법

1. 잘못된 요청 확인

• 에러 로그에서 문제가 되는 요청 URI를 확인하세요.
• % 문자 이후에 두 자리 16진수가 아닌 값이 있는지 확인합니다.

예:

?q=%ZZ → 잘못된 인코딩
?q=%20 → 올바른 인코딩 (공백)

2. URL 인코딩 검증 로직 적용 (클라이언트 또는 프론트엔드)

• 자바스크립트에서 encodeURIComponent() 함수를 사용하여 올바른 인코딩 값을 생성하세요.
• 사용자 입력을 인코딩하지 않고 직접 URL에 포함시키는 경우 위와 같은 문제가 발생할 수 있습니다.

예:

const userInput = "공백 포함";
const encoded = encodeURIComponent(userInput); // %EA%B3%B5%EB%B0%B1%20%ED%8F%AC%ED%95%A8

3. 서버 필터 또는 인터셉터에서 사전 차단

• Spring에서 Filter 또는 Interceptor를 활용하여 요청 URI를 점검하고,
  비정상적인 인코딩을 사전 차단하거나 로깅을 통해 추적할 수 있습니다.

예시 (Filter 적용):

public class UrlEncodingFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
        throws IOException, ServletException {
        try {
            String uri = ((HttpServletRequest) request).getRequestURI();
            URLDecoder.decode(uri, StandardCharsets.UTF_8.name()); // 테스트 디코딩
            chain.doFilter(request, response);
        } catch (IllegalArgumentException e) {
            throw new ServletException("Invalid URL encoding detected", e);
        }
    }
}

---

정리

이 오류는 단순한 오타나 사용자 입력 실수에서 시작될 수 있지만,
프론트엔드와 백엔드 양쪽에서 적절한 인코딩 처리와 방어 로직을 구현하지 않으면
서비스 전체의 안정성을 해칠 수 있습니다.

정상적인 인코딩은 사용자 경험과 시스템 신뢰도를 지키는 기본입니다.
에러 발생 시 로그를 빠르게 확인하고,
클라이언트-서버 간의 인코딩 정책을 다시 점검해 보세요.

---