はじめに
Spring Boot を使っていると、
「Bean が見つからない」 というエラーに必ず出会います。
- 起動時に落ちる
- DI がうまくいかない
- @Autowired でエラーになる
- Service が見つからないと言われる
こういったエラーは、
Bean の仕組みとスキャン範囲 を理解すると一気に解決します。
この記事では、Bean が見つからないときに
最初に確認すべきポイントを
やさしく・実務寄り で整理していきます。
よく出るエラーメッセージ
NoSuchBeanDefinitionException
No qualifying bean of type 'UserService' available
UnsatisfiedDependencyException
Error creating bean with name 'userController':
Unsatisfied dependency expressed through field 'userService'
どちらも 「DI したい Bean が見つからない」 という意味です。
Bean が見つからない原因（全体像）
1. アノテーションの付け忘れ
2. パッケージがスキャン範囲外
3. インターフェースと実装の不一致
4. @Profile による除外
5. Bean が複数あってどれを使うか決められない
6. コンストラクタの依存関係が循環している
アノテーションの付け忘れ（最も多い）
よくあるミス
- @Service を付け忘れ
- @Repository を付け忘れ
- @Component を付け忘れ
例
public class UserService { ... } // ← @Service がない対策
@Service
public class UserService { ... }Bean として登録されていない → 見つからない
というシンプルな原因です。
パッケージがスキャン範囲外
Spring Boot は Application クラスのパッケージ配下を自動スキャン します。
よくあるミス
com.example.demo ← Application
com.example.service ← ここは OK
com.other.service ← ここはスキャンされない
対策
- Application と同じ階層か配下に置く
- または @ComponentScan を使う
インターフェースと実装の不一致
よくあるミス
@Autowired
private UserService userService; // インターフェース
@Service
public class UserServiceImpl2 implements UserService { ... } // 名前違いBean 名が違っても問題ありませんが、
実装クラスが存在しない とエラーになります。
@Profile による除外
よくあるミス
@Profile("prod")
@Service
public class ProdMailService { ... }dev で起動しているのに prod の Bean を探してしまうパターン。
対策
- active プロファイルを確認
- @Profile の指定を見直す
Bean が複数あってどれを使うか決められない
よくあるエラー
NoUniqueBeanDefinitionException
例
@Service
public class AService implements XService { }
@Service
public class BService implements XService { }対策
@Qualifier("aService")
private XService service;循環依存（Circular Dependency）
よくあるパターン
- AService が BService を @Autowired
- BService が AService を @Autowired
エラー例
Requested bean is currently in creation
対策
- 設計を見直す
- 片方をコンストラクタ DI → setter DI に変更
実務でのチェックリスト
アノテーションは付いているか
@Service / @Repository / @Component
Application 配下にあるか
パッケージ構造を確認。
インターフェースと実装は一致しているか
実装クラスが存在するか。
@Profile で除外されていないか
active プロファイルを確認。
Bean が複数ないか
NoUniqueBeanDefinitionException を確認。
循環依存がないか
依存関係を見直す。
ログの読み方（おさらい）
Bean が見つからないときは、
ログの最後にこう出ます。
UnsatisfiedDependencyException
NoSuchBeanDefinitionException
そして Caused by の行に真犯人が書かれています。
まとめ
Bean が見つからないエラーは、
「Bean が登録されていない」
「スキャンされていない」
「複数あって選べない」
のどれかです。
- アノテーションの付け忘れ
- パッケージがスキャン範囲外
- インターフェースと実装の不一致
- @Profile による除外
- Bean が複数
- 循環依存
難しく聞こえますが、
「Bean が登録されているか？」
「Spring がそのクラスを見えているか？」
の 2 点を確認すれば十分です。
Bean が見つからないエラーは、
最初は怖く見えますが、
“原因のパターン” を知っているだけで
落ち着いて対処できるようになります。
あなたの開発が、今日より少しだけ楽になりますように。
Spring さんが“見つけられないよ〜”って言ってるだけなんだね…
かわいいエラーだね。
コメント