java.lang.IllegalArgumentException: Invalid URL encoding – not a valid digit

웹 애플리케이션에서 URL 파라미터 처리 중 다음과 같은 예외가 발생할 수 있습니다.

---

에러 메시지

java.lang.IllegalArgumentException: Invalid URL encoding: not a valid digit: 118

---

예외 의미

이 오류는 URL 디코딩 중, %로 시작하는 인코딩 문자열이 올바른 16진수 형식이 아닌 경우에 발생합니다.

예: 클라이언트가 다음과 같은 URL을 요청한 경우

https://example.com/search?q=%u0118

또는

?q=%118 → 잘못된 인코딩 (118은 16진수가 아님)

Java는 % 다음의 두 자리를 16진수(09, AF)로 해석하려고 시도하지만,
118처럼 세 자리이거나 숫자만 있는 경우는 유효하지 않기 때문에 예외가 발생합니다.

---

🔍 주요 발생 원인

원인	설명
URL 직접 입력	사용자가 주소창에 %118, %uXXXX 등 비표준 인코딩을 입력
자바스크립트 인코딩 오류	escape() 또는 수동 인코딩 방식 사용 시 유효하지 않은 값 포함
잘못된 요청 툴 사용	Postman, curl 등에서 URL 인코딩을 누락하거나 잘못 처리한 경우
공격 또는 스캐닝	웹 스캐너가 의도적으로 잘못된 인코딩을 삽입하여 서버 반응을 유도

---

해결 방법

1. 프론트엔드에서 올바른 인코딩 사용

자바스크립트에서 URL을 구성할 때 반드시 encodeURIComponent()를 사용해야 합니다.

const keyword = "예시 문자열";
const encoded = encodeURIComponent(keyword); // 안전한 인코딩

escape() 함수는 더 이상 권장되지 않으며, UTF-8 인코딩을 제대로 지원하지 않으므로 사용 금지

---

2. 잘못된 요청에 대한 예외 처리 추가

서버에서 디코딩 예외를 감지할 수 있는 try-catch 구문 또는 예외 전용 필터를 추가해보세요.

try {
    String decoded = URLDecoder.decode(request.getParameter("q"), StandardCharsets.UTF_8.name());
} catch (IllegalArgumentException e) {
    log.warn("잘못된 URL 인코딩 요청 감지: {}", request.getQueryString());
    response.sendError(HttpServletResponse.SC_BAD_REQUEST, "Invalid URL Encoding");
    return;
}

---

3. 방화벽 또는 WAF 설정 점검

웹 방화벽(WAF) 또는 보안 솔루션에서 비표준 URL 인코딩 차단 정책을 설정할 수 있습니다.
특히 자동화된 스캐닝 도구로부터 시스템을 보호하는 데 효과적입니다.

---

4. 로그 모니터링 및 분석

에러 발생 시점의 로그를 통해 공격 시도 또는 클라이언트 오류 여부를 판단할 수 있습니다.
반복적으로 발생한다면 패턴 분석 및 IP 차단 등의 보안 조치도 고려해야 합니다.

---

결론

이 오류는 단순한 오타부터 악의적인 스캐닝까지 다양한 원인에서 발생할 수 있습니다.
사용자 입력을 안전하게 처리하고, 예외 상황에 유연하게 대응할 수 있도록
프론트엔드와 백엔드 양쪽 모두에서 인코딩 로직을 철저히 점검해야 합니다.

---