SelfCheck_AI Troubleshooting_1(26.01.22)

❗ 문제 상황

Spring Boot 애플리케이션 실행 시
아래와 같은 오류가 발생하며 서버가 기동되지 않았다.

Ambiguous @ExceptionHandler method mapped for [class java.lang.Exception]

에러 로그에 따르면
GlobalExceptionHandler 내부의 @ExceptionHandler 설정이 충돌하고 있었다.

🔍 문제 원인 분석

GlobalExceptionHandler에는 다음과 같은 예외 처리 메서드가 존재했다.

@ExceptionHandler(MethodArgumentNotValidException.class)
public ApiResponse<?> handleValidationException(...)

@ExceptionHandler(Exception.class)
public ApiResponse<?> handleException(Exception e)

문제는 예외 상속 구조에 있었다.

MethodArgumentNotValidException
 └─ BindException
    └─ Exception

즉,

• MethodArgumentNotValidException은
  Exception의 하위 클래스
• Spring 입장에서는
  두 개의 핸들러가 동시에 처리 가능한 상태

이로 인해 Spring은

“이 예외를 어느 핸들러가 처리해야 할지 모르겠다”

라고 판단했고,
ApplicationContext 초기화 단계에서 실패하게 되었다.

💡 핵심 원인 정리

• @ExceptionHandler(Exception.class)는 너무 광범위
• 이미 더 구체적인 예외 핸들러가 존재하는 상황에서
• 상위 타입을 다시 처리하려 해 Ambiguous(모호함) 발생

✅ 해결 방법

가장 일반적인 예외 처리 대상이었던
Exception.class를 다음과 같이 변경했다.

@ExceptionHandler(RuntimeException.class)
public ApiResponse<?> handleRuntimeException(RuntimeException e) {
    return ApiResponse.error(
        ErrorCode.INTERNAL_ERROR.name(),
        ErrorCode.INTERNAL_ERROR.getDefaultMessage()
    );
}

왜 RuntimeException인가?

• Spring MVC 내부 예외 대부분이 RuntimeException 기반
• Checked Exception(Exception)은 직접 다루는 경우가 거의 없음
• 예외 범위를 명확히 좁혀 충돌 방지

🎉 해결 결과

• 애플리케이션 정상 기동
• /health 엔드포인트 정상 응답
• GlobalExceptionHandler 구조 안정화

{
  "success": true,
  "data": "OK",
  "error": null
}

🧠 정리하며 얻은 교훈

• 예외도 설계 대상이다
• 너무 넓은 예외 타입을 잡으면 오히려 시스템이 불안정해진다
• @ExceptionHandler는
  “정말 내가 책임질 수 있는 예외만” 처리해야 한다