[JAVA] Whitelabel Error Page 원인 추적 방법

Spring Boot에서 Whitelabel Error Page가 나타나면 막막하게 느껴지는 경우가 많습니다. 단순 에러 페이지처럼 보이지만, 실제로는 서버 내부에서 예외가 발생했다는 신호입니다. Whitelabel Error Page의 원인을 어떻게 추적하는지 정리합니다.

Whitelabel Error Page란 무엇인가

Whitelabel Error Page는 Spring Boot에서 기본으로 제공하는 에러 페이지입니다. 별도의 에러 페이지를 정의하지 않았을 때, 서버에서 예외가 발생하면 이 화면이 노출됩니다.

중요한 점은 이 페이지 자체가 문제가 아니라, 내부에서 처리되지 않은 예외가 있다는 사실입니다. 따라서 화면을 바꾸는 것이 아니라, 예외의 원인을 찾는 것이 중요합니다.

 

자주 발생하는 상황

다음과 같은 경우에 Whitelabel Error Page가 자주 나타납니다.

- Controller에서 예외가 발생했지만 처리되지 않은 경우
- 잘못된 URL 요청 (404)
- 내부 로직에서 RuntimeException 발생
- View 템플릿 렌더링 실패

 

원인 추적의 핵심은 로그입니다

Whitelabel Error Page 원인 추적의 시작점은 로그입니다. 화면만 보고 판단하면 거의 해결되지 않습니다.

실무에서는 에러 페이지보다 서버 로그를 먼저 확인하는 흐름이 자연스럽습니다. 특히 stack trace를 중심으로 보는 것이 중요합니다.

로그에서 확인해야 하는 포인트

다음 순서로 로그를 보는 것이 효과적입니다.

1. Exception 종류 확인
2. 메시지 내용 확인
3. stack trace에서 최초 발생 위치 찾기

java.lang.NullPointerException: Cannot invoke "User.getName()" because "user" is null
    at com.example.service.UserService.getUserName(UserService.java:25)
    at com.example.controller.UserController.getUser(UserController.java:18)

이 경우 실제 원인은 Controller가 아니라 Service 레이어에서 발생한 NullPointerException입니다. stack trace를 끝까지 내려보지 않으면 위치를 잘못 판단하기 쉽습니다.

 

HTTP 상태 코드로 1차 분류하기

Whitelabel Error Page가 나타날 때는 HTTP 상태 코드로 먼저 범위를 좁히는 것이 좋습니다.

404 Not Found

요청한 URL이 존재하지 않는 경우입니다. 이 경우는 로직 문제가 아니라 매핑 문제일 가능성이 높습니다.

@GetMapping("/users")
public List<User> getUsers() {
    return userService.findAll();
}

위 코드에서 /user로 요청하면 404가 발생합니다. URL 오타나 경로 변경 시 자주 발생합니다.

500 Internal Server Error

서버 내부에서 예외가 발생한 경우입니다. 이 경우는 반드시 로그를 확인해야 합니다.

단순히 "에러가 났다" 수준이 아니라, 어떤 클래스에서 어떤 이유로 실패했는지를 찾아야 합니다.

 

자주 헷갈리는 포인트

Whitelabel Error Page를 처음 접하면 화면만 보고 원인을 추측하는 경우가 많습니다. 하지만 대부분의 경우는 로그를 보면 바로 드러납니다.

또 하나 자주 놓치는 부분은 예외가 여러 번 감싸져 있는 경우입니다. Spring에서는 예외를 wrapping 하는 경우가 많아서, 가장 바깥 Exception이 아니라 내부 root cause를 찾아야 합니다.

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

이 경우 실제 원인은 IllegalArgumentException입니다. 겉에 보이는 예외만 보고 판단하면 방향이 틀어질 수 있습니다.

 

에러 페이지를 커스터마이징할 것인가

Whitelabel Error Page 자체를 커스터마이징하는 것도 가능합니다. 하지만 원인 추적과는 별개의 문제입니다.

운영 환경에서는 사용자에게 기본 에러 페이지를 그대로 보여주는 것은 좋지 않기 때문에, 별도의 에러 페이지를 구성하는 경우가 많습니다.

server.error.whitelabel.enabled=false

이 설정으로 기본 페이지를 비활성화할 수 있습니다. 다만, 에러를 숨기는 것이 아니라 사용자 경험을 개선하는 용도로 보는 것이 맞습니다.

 

정리

Whitelabel Error Page는 문제의 원인이 아니라 결과입니다. 화면 자체를 분석하는 것보다, 로그를 통해 예외를 추적하는 것이 훨씬 빠릅니다.

정리하면 다음과 같이 접근하는 것이 좋습니다.

- HTTP 상태 코드로 1차 분류
- 서버 로그에서 Exception 확인
- stack trace 기준으로 최초 발생 위치 추적
- wrapping된 예외 내부까지 확인

이 흐름이 익숙해지면 Whitelabel Error Page는 더 이상 막막한 문제가 아닙니다. 단순한 에러 화면이 아니라, 디버깅의 출발점으로 보면 됩니다.