공포의 하얀 화면! 스프링 부트 Whitelabel Error Page (404) 원인과 해결법 완벽 정리

안녕하세요, 여러분의 든든한 IT 길잡이 데브프리입니다.

 

스프링 부트(Spring Boot)로 씬나게 코딩을 하고 설레는 마음으로 서버를 실행한 뒤 브라우저에 접속했을 때, 예쁜 화면 대신 우리를 반겨주는 크고 차가운 하얀색 화면을 마주한 적 있으신가요?

 

Whitelabel Error Page

This application has no explicit mapping for /error, so you are seeing this as a fallback.

There was an unexpected error (type=Not Found, status=404).

 

개발자들 사이에서 일명 '공포의 백지 화면'이라고 불리는 Whitelabel Error Page (404 Not Found) 에러입니다. 분명 서버는 정상적으로 켜졌는데 왜 화면이 나오지 않는 걸까요?

 

오늘은 초보 개발자들의 멘탈을 바사삭 부수어버리는 이 하얀 화면이 도대체 왜 뜨는 것인지 그 원인을 짚어보고, 스프링 부트 환경에서 가장 흔하게 실수하는 2가지 원인과 해결 방법까지 확실하게 정리해 드리겠습니다!

 

1. 404 Not Found, 도대체 넌 누구냐? (없는 주소 배달 비유)

404 Not Found 에러는 웹의 세계에서 가장 유명한 에러 코드입니다. 그 의미는 아주 단순명쾌합니다. "네가 찾는 그 페이지(자원), 우리 서버에는 없는데?"라는 뜻입니다.

404 에러는 배달원(브라우저)이 서버라는 건물에 도착했지만, 요청받은 호실(URL 주소)이 아예 존재하지 않을 때 발생합니다.

일상생활에 비유해 볼까요?

여러분이 택배 기사님에게 "스프링 아파트 101동 505호로 배달해 주세요!"라고 요청했습니다. 기사님이 아파트에 도착해서 5층에 올라갔는데, 501호부터 504호까지만 있고 505호라는 문 자체가 아예 없는 상황입니다.

 

자바에서도 똑같습니다. 클라이언트(브라우저)가 http://localhost:8080/hello라는 주소로 데이터를 달라고 요청했는데, 스프링 부트 서버 안에 /hello라는 주소를 처리할 컨트롤러(문)가 만들어져 있지 않을 때 스프링 부트가 기본적으로 띄워주는 경고문이 바로 Whitelabel Error Page입니다.

 

2. 스프링 부트에서 404 에러를 해결하는 2가지 방법

서버는 멀쩡한데 주소를 찾지 못하는 것이므로, 해결 원리는 간단합니다. 브라우저가 요청한 주소와 스프링 부트 컨트롤러에 적힌 주소를 완벽하게 일치시키거나, 컨트롤러가 스프링에게 제대로 인식되도록 위치를 잡아주는 것입니다.

브라우저가 요청한 주소와 서버의 컨트롤러 주소를 정확하게 연결(Mapping)해주면 하얀 화면은 즉시 사라집니다.

스프링 부트 환경에서 404 에러가 발생했다면 십중팔구 아래 2가지 실수 때문입니다.

방법 ①: URL 경로 오타 및 HTTP 메서드 불일치 (가장 흔한 실수)

가장 먼저 확인해야 할 것은 브라우저 주소창에 친 주소와, 내 코드의 @GetMapping에 적힌 주소가 오타 없이 정확히 일치하는지 확인하는 것입니다.

[잘못된 코드 - 404 발생]

Java

 

@RestController
public class HelloController {
    
    // 🚨 코드에는 /helloworld 라고 적어놓고, 브라우저에서는 /hello 로 접속한 경우!
    @GetMapping("/helloworld")
    public String hello() {
        return "안녕하세요!";
    }
}

또한, 주소는 맞지만 데이터를 달라고 하는 방식이 틀린 경우도 있습니다. 브라우저 주소창에 엔터를 치는 것은 무조건 GET 방식인데, 코드에는 @PostMapping으로 적어두었다면 스프링은 "이 주소로 GET 요청을 처리할 문은 없는데?"라며 404 에러를 뱉어냅니다. (혹은 405 Method Not Allowed)

방법 ②: 패키지 위치 이탈 (컴포넌트 스캔 실패)

주소 오타도 없는데 404가 뜬다면 100% 이 문제입니다. 스프링 부트는 메인 실행 클래스(@SpringBootApplication이 붙은 클래스)가 있는 같은 패키지 혹은 그 하위 패키지만 뒤져서 컨트롤러를 찾아냅니다.

[잘못된 패키지 구조 - 404 발생]

• com.devfree.demo (메인 클래스 위치)
  • DemoApplication.java
• com.devfree.controller (🚨 메인 클래스와 동급이거나 상위 패키지에 위치)
  • HelloController.java (스프링이 이 컨트롤러를 아예 찾지 못함!)

[해결된 패키지 구조] 반드시 컨트롤러를 메인 클래스가 들어있는 패키지 아래(하위)로 이동시켜야 합니다.

• com.devfree.demo (메인 클래스 위치)
  • DemoApplication.java
  • controller (폴더 생성)
    • HelloController.java (정상적으로 스캔됨!)

 

3. 요약: 트러블슈팅 체크리스트

Whitelabel Error Page를 마주했다면 당황하지 말고 아래 3가지를 체크하세요.

1. 주소창 오타 확인: 브라우저에 입력한 주소(http://localhost:8080/주소)와 컨트롤러의 @GetMapping("/주소")가 슬래시(/) 하나까지 정확히 일치하는지 확인합니다.
2. HTTP 메서드 확인: 화면을 단순히 보여달라는 요청인데 @PostMapping이나 @PutMapping을 사용하지 않았는지 확인합니다. 기본 조회는 무조건 @GetMapping입니다.
3. 컨트롤러 패키지 위치 확인: 내 컨트롤러 파일이 ~Application.java 파일이 있는 폴더와 같거나, 그 하위 폴더에 예쁘게 들어가 있는지 폴더 구조(Tree)를 확인합니다.

 

마무리

처음 스프링 부트를 켰을 때 만나는 하얀 화면은 등골을 서늘하게 만들지만, 사실 알고 보면 에러 중에서도 가장 귀여운(?) 에러입니다.

 

문법이 틀려서 컴퓨터가 망가진 것이 아니라, 단순히 "너네 집 주소를 못 찾겠어!"라는 귀여운 투정에 불과하니까요. 컨트롤러의 위치와 오타만 잘 확인하면 이 하얀 화면은 금세 여러분이 원하는 예쁜 웹 페이지로 바뀔 것입니다.

 

오늘 준비한 트러블슈팅 가이드가 여러분의 하얀 에러 창을 깨끗하게 지워주었기를 바랍니다. 오류를 고친 경험은 여러분의 가장 큰 자산이 됩니다. 막히는 에러가 있다면 언제든 댓글로 남겨주세요.

 

지금까지 데브프리였습니다. 감사합니다!