Spring BeanCreationException 원인 TOP 5 (실무 해결 체크리스트)

 

Spring Boot 실행 시 자주 발생하는 BeanCreationException 원인 TOP 5를 실무 기준으로 정리했습니다.

@Autowired 주입 실패, ComponentScan 문제, 순환참조, 설정값 placeholder 오류, Bean 중복 등록 등 대표 케이스별 해결 방법과 체크리스트를 확인하세요.

 

 

 

Spring BeanCreationException 자주 나오는 원인 TOP 5 (실무 해결 체크리스트)

Spring Boot 프로젝트를 실행하다 보면 자주 보이는 에러가 있습니다.

org.springframework.beans.factory.BeanCreationException

대부분 개발자들이 처음 이 에러를 보면 이렇게 느낍니다.

• “Bean 생성이 실패했다는데… 뭐가 문제인지 모르겠음”
• “코드를 안 바꿨는데 갑자기 터짐”
• “로그가 너무 길어서 원인 파악이 힘듦”

하지만 BeanCreationException은 대부분 반복되는 몇 가지 이유에서 발생합니다.

오늘은 실무에서 가장 자주 나오는 BeanCreationException 원인 TOP 5를 정리하고,
각각의 해결 방법을 체크리스트 형태로 정리해보겠습니다.

---

1. BeanCreationException이란?

Spring이 실행될 때 ApplicationContext를 구성하면서

• @Component, @Service, @Repository, @Configuration 등으로 등록된 빈을 생성하고
• 의존성 주입(@Autowired, 생성자 주입)을 하고
• 설정값(yml/properties)을 바인딩하고
• 프록시(AOP, Transaction)를 만들고

이 과정 중 하나라도 실패하면 BeanCreationException이 발생합니다.

📌 핵심

BeanCreationException 자체는 “결과”일 뿐이고
진짜 원인은 로그 아래쪽 Caused by: 를 봐야 합니다.

---

2. 원인 TOP 5 한눈에 요약

순위원인대표 증상

1	빈 주입 실패(@Autowired)	NoSuchBeanDefinitionException
2	ComponentScan/패키지 문제	Controller/Service가 빈 등록 안됨
3	Bean 중복 등록	expected single matching bean but found 2
4	순환 참조	BeanCurrentlyInCreationException
5	설정값 바인딩 실패	Could not resolve placeholder / Failed to bind properties

---

3. 원인 1) @Autowired 주입 실패(빈이 없음)

가장 흔합니다.

예를 들어 아래처럼 주입을 했는데,

 

@Service public class OrderService { @Autowired private PaymentService paymentService; }

PaymentService가 Bean으로 등록이 안돼있으면 빈 생성이 실패합니다.

대표 로그

• NoSuchBeanDefinitionException
• required a bean of type ... that could not be found

해결 체크

✅ PaymentService에 @Service/@Component 붙었는지
✅ 인터페이스만 있고 구현체 빈 등록이 안 된 건 아닌지
✅ 스캔 패키지 안에 존재하는지

---

4. 원인 2) ComponentScan / 패키지 구조 문제

Spring Boot는 기본적으로

@SpringBootApplication 클래스 기준으로 하위 패키지만 스캔합니다.

예:

 

com.example.demo (여기 Application 클래스) com.example.service (하위 아님)

이면 service가 등록되지 않아서 주입 실패 → BeanCreationException으로 이어집니다.

해결 방법

✅ 패키지 구조를 하위로 통일
또는 강제 스캔

 

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

---

5. 원인 3) Bean 중복 등록(동일 타입/동일 이름)

빈이 2개 이상 등록되었는데 Spring이 어느 걸 써야할지 모르면서 터집니다.

예: PaymentService 구현체가 두 개

 

@Service public class KakaoPayService implements PaymentService {}
@Service public class NaverPayService implements PaymentService {}

그리고 주입은 이렇게 하면?

 

@Autowired private PaymentService paymentService;

대표 로그

• expected single matching bean but found 2

해결 방법

✅ @Qualifier 사용

 

@Autowired @Qualifier("kakaoPayService") private PaymentService paymentService;

@Autowired
@Qualifier("kakaoPayService") private PaymentService paymentService;

✅ 또는 @Primary 사용

 

@Primary
@Service public class KakaoPayService implements PaymentService {}

---

6. 원인 4) 순환 참조(Circular dependency)

A가 B를 주입하고, B가 다시 A를 주입하면 빈 생성이 불가능합니다.

 

@Service public class AService { @Autowired private BService bService; }
@Service public class BService { @Autowired private AService aService; }

대표 로그

• BeanCurrentlyInCreationException

해결 방법

✅ 구조 변경(가장 추천)
✅ @Lazy로 임시 회피

 

@Autowired @Lazy private AService aService;

단, @Lazy는 임시방편이므로 실무에서는 의존성 구조를 분리하는 걸 추천합니다.

---

7. 원인 5) 설정값(application.yml) 바인딩 실패

설정값 오류도 Bean 생성 실패로 연결됩니다.

대표 로그

• Could not resolve placeholder
• Failed to bind properties under ...

예:

 

spring: datasource: url: jdbc:oracle:thin:@localhost:1521:xe username: scott password:

password가 비어있거나 profile이 꼬이면 터질 수 있습니다.

해결 체크

✅ yml 들여쓰기/띄어쓰기
✅ profile(dev/prd) 올바른지
✅ 환경변수 누락 여부

---

✅ 결론: BeanCreationException 실무 해결 순서

BeanCreationException은 “원인”이 아니라 “결과”입니다.

실무에서는 아래 순서대로 보면 가장 빠릅니다.

1. 로그에서 Caused by: 첫 번째 원인 찾기
2. @Autowired 주입 대상 빈이 등록됐는지 확인
3. ComponentScan/패키지 구조 확인
4. 빈 중복 등록 여부 확인(@Primary, @Qualifier)
5. 설정값(yml/properties) 바인딩 확인