[JAVA] BeanCreationException 원인 찾는 방법 (실무 기준)

Spring Boot를 사용하다 보면 BeanCreationException은 한 번쯤 반드시 마주하게 됩니다. 문제는 에러 메시지가 길고, 실제 원인은 다른 곳에 숨어 있는 경우가 많다는 점입니다.

BeanCreationException 원인 찾는 방법 (실무 기준)

BeanCreationException은 Spring 컨테이너가 Bean을 생성하는 과정에서 실패했을 때 발생하는 예외입니다. 단순히 Bean 생성 실패라고만 보면 범위가 너무 넓기 때문에, 실제로는 "어떤 단계에서 왜 실패했는지"를 구분해서 접근해야 합니다.

 

BeanCreationException의 본질

이 예외는 독립적인 원인이라기보다는, 내부에서 발생한 다른 예외를 감싸는 wrapper 역할을 하는 경우가 대부분입니다. 즉, 진짜 원인은 내부의 Caused by를 확인해야 드러납니다.

처음 접하면 BeanCreationException 자체를 해결하려고 하기 쉽지만, 실제로는 하위 예외를 따라가는 것이 중요합니다.

 

원인 추적의 기본 흐름

실무에서는 아래 순서로 접근하는 것이 가장 빠릅니다.

1. 가장 마지막 Caused by부터 확인

스택 트레이스를 보면 BeanCreationException이 여러 번 감싸져 있는 경우가 많습니다. 이때 가장 아래쪽 Caused by를 먼저 보는 것이 좋습니다.

Caused by: java.lang.NullPointerException

위처럼 실제 원인이 NullPointerException일 수도 있고, ClassNotFoundException일 수도 있습니다.

겉에 보이는 BeanCreationException만 보면 방향을 잘못 잡기 쉽습니다.

2. 어떤 Bean에서 발생했는지 확인

에러 메시지에는 실패한 Bean 이름이 포함됩니다.

Error creating bean with name 'userService'

이 Bean이 직접 문제일 수도 있고, 의존하고 있는 다른 Bean이 문제일 수도 있습니다. 따라서 해당 Bean의 생성자나 @Autowired 필드를 같이 확인해야 합니다.

3. 의존 관계 따라가기

Spring은 Bean을 생성할 때 의존 관계를 따라 올라가면서 생성합니다. 따라서 한 Bean에서 실패하면, 상위 Bean들도 연쇄적으로 실패합니다.

이 때문에 실제 문제는 아래쪽 Bean인데, 위쪽 Service에서 에러가 난 것처럼 보이는 경우가 많습니다.

 

자주 발생하는 원인 유형

1. 의존성 주입 실패

가장 흔한 케이스입니다. Bean으로 등록되지 않은 클래스를 주입하려고 할 때 발생합니다.

@Service
public class UserService {
    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
}

UserRepository에 @Repository나 @Component가 없다면 Bean 생성이 실패합니다.

이 부분은 패키지 스캔 범위 문제와 같이 묶여서 발생하는 경우도 많습니다.

2. 순환 참조 (Circular Dependency)

서로를 참조하는 Bean이 있을 경우 발생합니다.

최근 Spring Boot에서는 기본적으로 순환 참조를 허용하지 않기 때문에, 구조 자체를 수정해야 하는 경우가 많습니다.

이 경우에는 @Lazy로 임시 해결할 수 있지만, 설계를 나누는 것이 더 명확한 방법입니다.

3. 설정값 누락 또는 잘못된 프로퍼티

application.yml 또는 application.properties의 값이 잘못된 경우에도 Bean 생성이 실패합니다.

특히 @Value나 @ConfigurationProperties를 사용할 때 많이 발생합니다.

@Value("${app.name}")
private String appName;

app.name이 없으면 Bean 생성 자체가 실패합니다.

4. 외부 라이브러리 또는 클래스 문제

ClassNotFoundException이나 NoSuchMethodError가 내부 원인인 경우도 있습니다.

이 경우는 보통 의존성 충돌이나 버전 문제에서 발생합니다.

빌드 파일을 확인해서 동일한 라이브러리가 여러 버전으로 포함되어 있는지 보는 것이 필요합니다.

 

실무에서 빠르게 해결하는 기준

BeanCreationException은 겉으로 보이는 메시지보다 내부 원인을 빠르게 찾는 것이 핵심입니다.

다음 기준으로 접근하면 시간을 많이 줄일 수 있습니다.

• 가장 마지막 Caused by부터 확인
• 실패한 Bean 이름 기준으로 코드 이동
• 해당 Bean의 생성자 의존성 점검
• 설정값 또는 환경 변수 확인

특히 의존성 주입 문제와 설정값 문제는 초기 단계에서 가장 많이 발생합니다.

 

정리

BeanCreationException은 자체적으로 문제를 설명해주는 예외라기보다는, 내부 예외를 감싸는 구조입니다.

따라서 해결의 핵심은 예외 메시지를 끝까지 내려가서 실제 원인을 찾는 것입니다.

처음에는 로그가 길어서 부담스럽게 느껴질 수 있지만, 원인을 찾는 흐름이 익숙해지면 대부분 빠르게 해결할 수 있습니다.