Spring Boot Whitelabel Error Page 해결 가이드 (404/500 원인별 정리)

Spring Boot에서 Whitelabel Error Page가 뜨는 원인(404, 500)을 구분하고 해결 방법을 정리했습니다.

Controller mapping 문제, context-path, View(JSP/Thymeleaf) 경로, Spring Security 설정, ErrorController(/error) 처리 방식까지 단계별로 확인할 수 있습니다.

 

 

 

Spring Boot Whitelabel Error Page 해결 가이드 (404/500 원인별 정리)

Spring Boot 프로젝트를 실행했는데 갑자기 아래 화면이 뜬 적 있으신가요?

Whitelabel Error Page
There was an unexpected error (type=Not Found, status=404).
There was an unexpected error (type=Internal Server Error, status=500).

처음 보면 “스프링이 망가진 건가?” 싶지만, 사실 Whitelabel Error Page는 스프링의 기본 오류 페이지일 뿐입니다.

즉,

스프링에서 에러가 발생했는데, 내가 따로 에러페이지를 만들지 않았을 때
Spring Boot가 기본으로 보여주는 화면

오늘은 Whitelabel Error Page가 뜨는 대표 원인을 404/500으로 나눠서 해결 가이드를 정리해보겠습니다.

---

1. Whitelabel Error Page란?

Whitelabel Error Page는

• /error 경로로 에러가 처리되었고
• 커스텀 에러페이지가 없을 때

Spring Boot가 제공하는 기본 페이지입니다.

✅ 중요한 포인트
Whitelabel 화면 자체가 문제가 아니라, 그 앞에 발생한 진짜 원인을 찾아야 합니다.

---

2. 먼저 확인: 404인지 500인지 구분하기

Whitelabel Error Page를 해결하는 가장 빠른 방법은 딱 하나예요.

status 코드 먼저 본다 (404냐, 500이냐)

✅ 404 Not Found

• Controller 매핑이 없음
• URL 경로가 잘못됨
• context-path 문제

✅ 500 Internal Server Error

• Controller는 잡혔는데 내부에서 터짐
• BeanCreationException, NullPointerException, DB 접속 실패 등

---

3. 원인 1) URL Mapping이 없음 (404)

가장 흔한 원인입니다.

예:

 

@GetMapping("/users") public String users() { return "ok"; }

근데 브라우저에서 아래로 접근하면?

• /user
• /users/
• /Users

👉 404가 납니다.

✅ 해결 체크리스트

• URL 오타
• 슬래시(/) 유무
• @RequestMapping 경로 조합 확인

---

4. 원인 2) View(JSP/Thymeleaf) 파일을 못 찾음

“Controller는 잡히는데 화면만 안나오고 Whitelabel 뜨는 경우”가 있습니다.

예)

 

@GetMapping("/home") public String home() { return "home"; }

Spring은 기본적으로

• JSP라면 /WEB-INF/views/home.jsp
• Thymeleaf라면 resources/templates/home.html

을 찾습니다.

✅ 해결 체크리스트

• view 파일이 실제로 존재하는지
• prefix/suffix 설정이 맞는지
• JSP라면 의존성이 포함돼 있는지

---

5. 원인 3) context-path 때문에 주소가 바뀜

application.yml에 아래 설정이 있으면

 

server: servlet: context-path: /myapp

원래 /users로 접근하던 것이 실제로는

✅ /myapp/users

로 바뀝니다.

이걸 모르고 /users로 호출하면 Whitelabel(404) 등장.

---

6. 원인 4) Spring Security 때문에 차단(403/redirect)

Spring Security를 적용하면

• 로그인 안 하면 로그인 페이지로 리다이렉트
• 권한 없으면 403

이런 처리가 생깁니다.

그런데 프론트/REST 호출에서는 “결과적으로 화면이 Whitelabel로 보이는” 상황이 발생할 수 있습니다.

✅ 해결 체크리스트

• Security 설정에서 permitAll 경로 확인
• static(js/css/img) 경로 허용 여부

예)

 

http.authorizeHttpRequests() .requestMatchers("/", "/login", "/css/**", "/js/**").permitAll() .anyRequest().authenticated();

---

7. 원인 5) 예외 발생으로 500 (Bean/DB/NullPointer)

Whitelabel 500이면 거의 100% “서버 내부 오류”입니다.

대표 원인

• BeanCreationException
• NullPointerException
• DB 연결 실패
• SQL 오류

✅ 해결 방법

• 무조건 콘솔 로그 확인 (가장 위 Caused by)
• 에러 발생 Controller/Service 확인

---

8. 해결 팁: error 로그 보는 방법

Whitelabel은 결과 화면이고
진짜 원인은 콘솔 로그에서 찾습니다.

특히 아래를 봐야 합니다.

• Caused by: 첫 번째
• stacktrace에서 내 패키지 경로(com.myapp...)가 찍히는 부분

---

9. 에러 페이지 커스터마이징(권장)

Whitelabel을 없애려면 방법이 2가지 있습니다.

방법 1) Whitelabel 끄기

 

server: error: whitelabel: enabled: false

방법 2) 커스텀 에러페이지 제공

정적 리소스 경로에 아래 파일을 추가하면 됩니다.

• resources/templates/error.html (Thymeleaf)
• 또는 resources/static/error/404.html
• resources/static/error/500.html

---

✅ 결론

Whitelabel Error Page가 뜨면 당황하지 말고,

1. 404인지 500인지 확인
2. 404면 URL/매핑/context-path
3. 500이면 콘솔 로그 Caused by
4. 마지막으로 에러페이지 커스터마이징

이 순서대로 보면 거의 다 해결됩니다.