Spring Boot 404 Not Found 에러 발생 원인과 해결 방법 총정리

Spring Boot 404 Not Found 에러 발생 원인과 해결 방법 총정리

Spring Boot로 웹 서비스를 개발하다 보면, 컨트롤러를 잘 작성했다고 생각했는데도 브라우저에서 404 Not Found 에러를 마주치는 경우가 많습니다.
404 에러는 요청한 URL에 해당하는 자원이 없을 때 발생하는데, 이는 단순 오타부터 설정 문제, 보안 필터, 배포 환경 이슈까지 원인이 다양합니다.

1. 404 Not Found란?

HTTP 상태 코드 404는 요청한 URL을 서버에서 찾을 수 없음을 의미합니다.
Spring Boot에서는 DispatcherServlet이 URL 매핑을 처리하는데, 매칭되는 컨트롤러가 없으면 404를 반환합니다.

2. 원인 1: 잘못된 @RequestMapping 또는 @GetMapping 경로

경로 앞뒤의 / 슬래시, 대소문자 불일치, 복수/단수 차이 등 사소한 오타로도 404가 발생합니다.

@RestController
@RequestMapping("/api")
public class TestController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello World";
    }
}

위 코드에서 /api/hello로 접근해야 하는데, /api/helloo 또는 /hello로 요청하면 404가 발생합니다.

3. 원인 2: 컨트롤러 스캔 범위 설정 문제

Spring Boot는 기본적으로 @SpringBootApplication이 선언된 클래스 패키지 하위만 컴포넌트 스캔합니다.
컨트롤러 클래스가 다른 패키지에 있으면 매핑이 등록되지 않습니다.

@SpringBootApplication(scanBasePackages = "com.example")
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

또는 @ComponentScan으로 명시적으로 패키지를 지정할 수 있습니다.

4. 원인 3: 정적 리소스와 경로 충돌

src/main/resources/static 또는 public 디렉토리에 같은 이름의 파일이 있으면, 컨트롤러 매핑보다 정적 리소스가 우선됩니다.

5. 원인 4: HTTP 메서드 불일치

같은 경로라도 GET/POST 등 메서드가 다르면 404 또는 405가 발생합니다.

@PostMapping("/submit")
public String submit() {
    return "OK";
}

여기에 GET 요청을 보내면 405(Method Not Allowed) 또는 404가 나타납니다.

6. 원인 5: 보안 설정 (Spring Security) 차단

Spring Security를 사용하는 경우, 특정 URL이 인증/인가 설정에 의해 차단되면 매핑이 무시되어 404가 발생할 수 있습니다.
이 경우 SecurityConfig에서 URL을 허용해야 합니다.

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
        .antMatchers("/api/**").permitAll()
        .anyRequest().authenticated();
}

7. 원인 6: 배포 환경 차이

• 로컬에서는 정상인데, 운영 서버에서는 서블릿 컨텍스트 경로가 달라 404 발생
• server.servlet.context-path 설정이 변경되었는지 확인 필요

8. 해결 체크리스트

• URL 경로 오타, 대소문자, 슬래시(/) 확인
• 컨트롤러 패키지가 스캔 범위 안에 있는지 확인
• 정적 리소스 경로와 충돌 여부 확인
• HTTP 메서드 일치 여부(GET, POST 등)
• Spring Security 차단 여부
• 배포 환경의 context-path 설정 확인

9. 예제: 전체 코드

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@RestController
@RequestMapping("/api")
class TestController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello World";
    }
}

맺음말

Spring Boot에서 404 Not Found는 가장 흔하지만 원인이 다양합니다.
단순 오타부터 패키지 구조, 보안 설정, 배포 환경 차이까지 꼼꼼히 확인하면 대부분 해결할 수 있습니다.
오늘 정리한 체크리스트를 활용해 문제를 빠르게 찾아 해결해 보세요.