Spring Boot Whitelabel Error Page 404 해결: 컨트롤러·컴포넌트 스캔·템플릿 경로 점검 순서 (Spring Boot 4.1.1, 2026년 9월 19일 확인)
스프링 부트를 띄우고 브라우저로 접속했더니 "Whitelabel Error Page"와 "This application has no explicit mapping for /error" 문구만 보이는 경우가 많습니다. 이 화면은 오류 원인이 아니라 스프링 부트가 준비해 둔 기본 오류 페이지이고, 진짜 원인은 함께 표시된 status 값에 있습니다. Spring Boot 4.1.1 공식 문서(2026년 9월 19일 확인) 기준으로 404 원인을 좁히는 순서를 정리했습니다.
빠른 결론
- Whitelabel 화면은 부트가 등록한 /error 기본 매핑이고, 404는 "요청 경로에 맞는 핸들러가 없다"는 뜻입니다.
- 컨트롤러 애노테이션, 컴포넌트 스캔 범위, 요청 경로·메서드, 템플릿·정적 파일 위치 네 가지만 보면 대부분 끝납니다.
- 화면을 바꾸려면
src/main/resources/static/error/404.html을 두거나spring.web.error.whitelabel.enabled=false로 끕니다.
먼저 상태 코드부터 구분하기
| 표시된 status | 의미 | 먼저 볼 곳 |
|---|---|---|
| 404 | 매핑된 핸들러가 없음 | 컨트롤러 등록 여부, 요청 경로, context-path |
| 500 | 핸들러는 실행됐지만 예외 발생 | 콘솔 스택 트레이스, 템플릿 이름 |
| 405 | 경로는 맞지만 HTTP 메서드가 다름 | @GetMapping과 @PostMapping 구분 |
| 401·403 | 스프링 시큐리티가 차단 | SecurityFilterChain 설정 |
점검 체크리스트
- 메인 클래스가 컨트롤러보다 상위 루트 패키지에 있는가
- JSON을 기대하면서
@Controller만 붙이고@ResponseBody를 빠뜨리지 않았는가 - 요청 URL이
server.servlet.context-path와 포트까지 포함해 정확한가 - 템플릿이
src/main/resources/templates에, 정적 파일이static·public·resources·META-INF/resources중 하나에 있는가
단계별 확인 순서
curl -i http://localhost:8080/경로로 요청해 status를 확인합니다. 기계 클라이언트에는 whitelabel 대신 JSON 오류 응답이 내려옵니다.- 애플리케이션 기동 로그에서 실제 포트와 컨텍스트 경로를 확인합니다. 포트를 바꿨다면 요청 주소도 함께 바꿔야 합니다.
- 컨트롤러 클래스에
@Controller또는@RestController가 붙어 있는지, 메서드에@GetMapping("/경로")가 있는지 확인합니다. - 컨트롤러 패키지가 메인 클래스 패키지의 하위인지 확인합니다. 공식 문서는 메인 클래스를 다른 클래스보다 상위 루트 패키지에 두라고 권장하며, 이 패키지가 컴포넌트 스캔 기준이 됩니다.
- 등록된 매핑을 직접 보려면
spring-boot-starter-actuator를 넣고management.endpoints.web.exposure.include=mappings를 설정한 뒤/actuator/mappings를 엽니다(기본 노출은 health뿐). @Controller에서 문자열을 반환한다면 그 이름의 템플릿이 실제로 있는지 확인합니다. 타임리프라면templates/이름.html입니다.- 정적 HTML이라면 파일을
src/main/resources/static에 두고 첫 화면은index.html로 만듭니다. 부트는 이 파일을 환영 페이지로 자동 사용합니다. - 정적 리소스 경로를 바꿨다면
spring.mvc.static-path-pattern(기본/**)과spring.web.resources.static-locations설정을 확인합니다.
오류 화면을 바꾸는 방법
- 상태 코드별 정적 페이지:
src/main/resources/public/error/404.html처럼 상태 코드 이름 그대로 파일을/error디렉터리에 둡니다. - 시리즈 단위 템플릿: 5xx 전체를 한 번에 처리하려면
templates/error/5xx템플릿 파일을 만듭니다. - 기본 화면 끄기:
spring.web.error.whitelabel.enabled=false를 설정합니다.
버전별 속성 이름 주의
Spring Boot 4.0부터 오류 관련 속성 이름이 바뀌었습니다. 공식 설정 변경 목록에서 server.error.* 속성들은 제거되고 spring.web.error.*로 대체됐습니다. 다른 글을 보고 server.error.whitelabel.enabled=false를 넣었는데 변화가 없다면 버전 차이일 가능성이 큽니다.
| 기능 | Spring Boot 3.5 이하 | Spring Boot 4.0 이상 |
|---|---|---|
| 기본 오류 페이지 끄기 | server.error.whitelabel.enabled | spring.web.error.whitelabel.enabled |
| 오류 경로 변경 | server.error.path | spring.web.error.path (기본 /error) |
| 메시지 포함 여부 | server.error.include-message | spring.web.error.include-message (기본 never) |
주의사항
spring.web.error.include-stacktrace를 운영 환경에서 켜 두면 내부 정보가 노출됩니다. 기본값은never입니다.- 실행 가능한 jar에서는 JSP가 지원되지 않고,
error.jsp로는 기본 오류 뷰를 대체할 수 없습니다. - jar 패키징에서는
src/main/webapp디렉터리가 무시되므로 정적 파일을 여기에 두면 404가 납니다.
그래도 404가 계속될 때
- IDE에서 실행 중인 애플리케이션이 두 개 떠 있지 않은지 확인합니다. 포트 충돌이면 기동 로그에 나타납니다.
- 스프링 시큐리티를 쓰고 있다면 403이 404처럼 보일 수 있으므로
logging.level.org.springframework.web=DEBUG로 요청 처리 로그를 확인합니다.
자주 묻는 질문
Q. Whitelabel Error Page가 뜨면 서버가 죽은 건가요?
A. 아닙니다. 서버는 정상 동작 중이며, 부트가 등록한 기본 오류 페이지가 표시된 것입니다. 함께 나온 status 값이 실제 원인입니다.
Q. 컨트롤러를 분명히 만들었는데도 404가 납니다.
A. 컨트롤러 패키지가 @SpringBootApplication 클래스의 하위 패키지인지 먼저 확인하세요. 상위나 다른 루트 패키지에 있으면 컴포넌트 스캔 대상에서 빠집니다.
Q. 404 화면만 예쁘게 바꾸고 싶습니다.
A. 정적 리소스 디렉터리 안에 error/404.html을 두면 됩니다. 별도 설정 없이 해당 상태 코드에서 사용됩니다.
함께 보면 좋은 글
- Spring Boot Port 8080 was already in use 오류 해결
- Spring Boot No qualifying bean of type 오류 해결
- Spring Boot Failed to configure a DataSource 해결
- IntelliJ Cannot resolve symbol 빨간 글씨 해결
공식 출처
- Spring Boot Reference, Servlet Web Applications - Error Handling, Custom Error Pages, Static Content, Welcome Page
- Spring Boot Reference, Structuring Your Code
- Spring Boot Appendix, Common Application Properties
- Spring Boot Wiki, Spring Boot 4.0 Configuration Changelog
기준: Spring Boot 4.1.1 문서, 2026년 9월 19일 확인. 사용하는 부트 버전에 맞는 문서를 함께 확인하세요.