404 Not Found 원인 7가지 정리 (Controller, ContextPath, Mapping)

Spring Boot 404 Not Found 원인 7가지 정리 (Controller, ContextPath, Mapping)

스프링부트 개발하다 보면 가장 자주 마주치는 에러 중 하나가 바로 404 Not Found 입니다.

특히 이런 화면으로 보이면 더 멘붕이죠.

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

그런데 404는 사실 복잡한 에러가 아닙니다.
딱 한 줄로 말하면 이거예요.

서버는 살아있는데, 요청한 URL에 해당하는 Mapping이 없다.

오늘은 Spring Boot에서 404가 발생하는 대표 원인 7가지를 실무에서 많이 터지는 순서대로 정리해보겠습니다.

---

1. 404 Not Found 먼저 의미부터 확인

HTTP 404는 “서버에 접속은 성공했지만, 해당 요청을 처리할 Controller/Resource가 없는 상태”입니다.

즉,

✅ 포트 접속은 됨
✅ 서버는 실행중임
❌ 근데 경로가 존재하지 않음

반대로 500이면 Controller는 잡혔는데 내부 로직에서 터진 거고,
404는 아예 Controller 매핑이 안 잡힌 상태라고 보면 됩니다.

---

2. 원인 1) URL 경로가 실제 Mapping과 다름 (대부분 이거)

가장 흔한 케이스입니다.

예)

 

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

근데 브라우저에서 아래처럼 요청하면?

 

/user /users/ /Users

404 뜹니다.

✅ 해결법

• URL 오타 없는지
• 대소문자 다른지
• 슬래시(/) 유무 확인

---

3. 원인 2) @RequestMapping / @GetMapping 경로 실수

Controller 클래스 레벨 + 메소드 레벨 mapping 조합 때문에 많이 헷갈립니다.

예)

 

@RestController @RequestMapping("/api") public class UserController {
    @GetMapping("/users") public String users() {
    	return "ok"; 
	}
}

이 경우 실제 URL은?
✅ /api/users

근데 /users로 호출하면 404 입니다.

✅ 해결법

• Controller 클래스에 @RequestMapping 붙어있는지 확인
• 실제 최종 경로를 머리로 조합하지 말고 적어서 체크

---

4. 원인 3) Controller 패키지 위치 문제 (ComponentScan)

이 케이스는 특히 신입/초기에 많이 걸립니다.

Spring Boot는 기본적으로 @SpringBootApplication 클래스가 있는 패키지를 기준으로
하위 패키지들만 스캔합니다.

예시 구조:

 

com.example.demo ├─ DemoApplication.java (여기 @SpringBootApplication) com.example.controller

├─ UserController.java (패키지가 아예 밖)

이러면 컨트롤러를 스캔 못해서 404가 납니다.

✅ 해결법 1) 컨트롤러 패키지를 하위로 이동
✅ 해결법 2) @ComponentScan 강제 지정

 

@SpringBootApplication @ComponentScan(basePackages = "com.example") 
public class DemoApplication {}

---

5. 원인 4) ContextPath 설정으로 URL이 바뀜

이거 실무에서 진짜 많음.

application.yml에 이런 설정 있으면

 

server: servlet: context-path: /myapp

기존에 /api/users로 호출하던게 이제는

✅ /myapp/api/users

로 바뀝니다.

그런데 기존 주소로 호출하면 404.

✅ 해결법

• context-path 설정 여부 확인
• swagger / postman 주소도 같이 수정

---

6. 원인 5) 포트/서버가 다른 애를 보고 있음

특히 운영/로컬 같이 쓰는 경우, 또는 서버가 여러 개 뜬 경우 자주 발생합니다.

예를 들어

• 로컬 spring boot: 8080
• 다른 서버/다른 app: 8081
• docker 서비스: 8080 점유

👉 내가 생각한 서버가 아닌 다른 서버를 보고 있어서 404가 뜨는 케이스.

✅ 해결법

• 콘솔 로그에서 포트 확인
• Tomcat started on port(s): 8080
• netstat로 확인

---

7. 원인 6) 정적 리소스(static) 우선순위 / 리소스 매핑 문제

Spring Boot는 기본적으로 정적 리소스를 아래 위치에서 찾습니다.

• src/main/resources/static
• src/main/resources/public

예:

 

static/index.html

이 경우 / 요청이 index.html로 떨어집니다.

근데 여기서 WebMvcConfigurer로 리소스 핸들러를 잘못 등록하거나
보안 설정(Spring Security)으로 막으면 404가 발생할 수 있습니다.

✅ 해결법

• 정적 경로 설정 확인
• security에서 permitAll 처리 필요

 

.requestMatchers("/css/**", "/js/**", "/images/**").permitAll()

---

8. 원인 7) View(JSP/Thymeleaf) 문제인데 404로 보이는 경우

이건 Controller는 잡혔는데, view를 못 찾는 경우입니다.

예: JSP인데 viewResolver 문제

 

@GetMapping("/home") public String home() {
	return "home"; // /WEB-INF/views/home.jsp 를 찾아야 함
}

• JSP 파일이 없거나
• prefix/suffix 설정이 꼬이면

404로 보일 수 있습니다.

✅ 해결법

• JSP 경로 확인
• view resolver 설정 점검

---

✅ 결론: 실무 점검 순서

Spring Boot 404가 뜨면 아래 순서대로 보면 빠릅니다.

1. URL 오타/슬래시 체크
2. @RequestMapping 경로 조합 확인
3. 컨트롤러 스캔되는 패키지인지 확인
4. context-path 설정 확인
5. 포트/서버 다른 곳 보고 있는지 확인
6. static 리소스 / security 설정 확인
7. view resolver 설정 확인