required a bean of typeの直し方｜原因一覧と読み方

「required a bean of type 'X' that could not be found」は、ある部品（Bean：Spring が作って管理するオブジェクト）が X を受け取ろうとしたのに、X の Bean が1つも登録されていなかったときのエラーです。 中身の例外は NoSuchBeanDefinitionException で、Spring Boot はこれを読みやすい形に直して表示します。

***************************
APPLICATION FAILED TO START
***************************

Description:

Parameter 0 of constructor in com.example.demo.order.OrderController required a bean of type 'com.example.demo.order.OrderService' that could not be found.


Action:

Consider defining a bean of type 'com.example.demo.order.OrderService' in your configuration.

直し方は、X が「なぜ登録されなかったか」を突き止めて、登録される状態にすることです。 多い原因は次のとおりです。

確認環境：Spring Boot 4.1.1（Spring Framework 7.0.9）、MyBatis Spring Boot Starter 4.1.0。エラー文は、それぞれの GitHub のタグのソースコード（NoSuchBeanDefinitionFailureAnalyzer・NoUniqueBeanDefinitionFailureAnalyzer・LoggingFailureAnalysisReporter など）とテストコードで確かめました。挙動の説明は docs.spring.io の Spring Boot リファレンスと、ソースで確かめた内容に基づきます（確認日 2026年10月12日）。

エラー表示の読み方（Description と Action）

APPLICATION FAILED TO START の表示は、Spring Boot の「FailureAnalyzer（起動失敗の原因を分析して説明文を作る部品）」が作ったものです。Description に「どこで」「何が足りないか」、Action に「どうするか」の提案が出ます。

Description の1文目で「どこで」が分かる

1文目の書き出しは、X を受け取ろうとした場所の形で変わります。ソースの書式は次のとおりです。

続く required a bean of type '〈型〉' が足りない Bean の型です。名前で探した場合は required a bean named '〈名前〉' になります。

読むときの順番は「型 → その型のクラスを開く → なぜ登録されないかを下の表で当てる」です。 1文目のクラス（受け取る側）を直しても解決しません。直すのは、'…' の中の型（受け取られる側）です。

Description の2段目に出る3種類の追加情報

ソースを読むと、1文目の後に、状況に応じて次の情報が足されます。

2つ目の見出しの下には、Bean method '〈メソッド名〉' in '〈クラス名〉' not loaded because 〈理由〉 の形で、作られなかった理由が並びます。理由の例（Spring Boot のテストコードにある文面）です。

The following candidates were found but could not be injected:
    - Bean method 'string' in 'TestPropertyAutoConfiguration' not loaded because @ConditionalOnProperty (spring.string.enabled) did not find property 'spring.string.enabled'
    - Bean method 'string' in 'TestMissingBeanAutoConfiguration' not loaded because @ConditionalOnBean (types: java.lang.Integer; SearchStrategy: all) did not find any beans
    - Bean method 'string' in 'TestPropertyAutoConfiguration' not loaded because auto-configuration 'TestPropertyAutoConfiguration' was excluded

この見出しが出たら、Bean を作るコードはあります。 足りないのは条件（プロパティ・クラス・ほかの Bean）なので、not loaded because の後ろを読めば直す場所が分かります。

Action の文は2通り

Action の「defining a bean（Bean を定義する）」は一般的な提案です。多くの場合は、新しく @Bean を書くより、既にあるクラスが登録されない原因を直すほうが正しい対処です。

例外の原文（スタックトレース側）

FailureAnalyzer の表示の上には、Spring Framework の例外がログに出ます。NoSuchBeanDefinitionException の文面はソースで次の書式でした。

org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type 'com.example.demo.order.OrderService' available: expected at least 1 bean which qualifies as autowire candidate. Dependency annotations: {}

Dependency annotations: {} の {} の中には、受け取る側に付いた注釈が入ります。@Qualifier("…") が出ていれば、名前の不一致を疑います。

原因1：@Service・@Component などの付け忘れ

Spring Boot は、注釈の付いたクラスだけを Bean として登録します。 注釈の無いクラスは、同じパッケージにあっても登録されません。

// 誤り：注釈が無いので Bean にならない
public class OrderService { … }

// 正しい
@Service
public class OrderService { … }

注釈をインターフェースに付けても Bean になりません。 部品探し（コンポーネントスキャン）は、new できる具体的なクラスだけを候補にします。

@Service                     // ← インターフェースに付けても登録されない
public interface OrderService { … }

@Service                     // ← 実装クラスに付ける
public class OrderServiceImpl implements OrderService { … }

@Bean メソッドで作る場合は、そのメソッドを書いたクラスに @Configuration が必要です。@Bean だけを普通のクラスに書いても、そのクラス自体が登録されていなければ実行されません。

原因2：起動クラスより上・横のパッケージにある

@SpringBootApplication を付けた起動クラスは、自分のパッケージとその下だけを探します。 上や横のパッケージにあるクラスは、注釈が付いていても見つかりません。

com.example.demo
 ├─ DemoApplication.java        ← @SpringBootApplication
 ├─ order
 │   └─ OrderService.java       ← 見つかる（下のパッケージ）
com.example.common
 └─ MailClient.java             ← 見つからない（横のパッケージ）

Spring Boot のリファレンスでは、起動クラスを「ほかのクラスより上の root パッケージ」に置くことを勧めています。

scanBasePackages を指定すると、起動クラスのパッケージは自動では入りません。 起動クラスのパッケージも一緒に書きます。

JPA のリポジトリやエンティティも同じ範囲で探されます。リポジトリだけが外にあるときは @EnableJpaRepositories、エンティティだけが外にあるときは @EntityScan で範囲を足します。パッケージの分け方は、関連記事「Spring Bootパッケージ構成｜層別と機能別のツリーと選び方の基準」で扱っています。

マルチモジュールのとき

共通部品を別モジュール（別の jar）に分けている場合は、パッケージだけでなく依存の設定も確かめます。

• 使う側のモジュールの build.gradle・pom.xml に、共通モジュールへの依存があるか
• 共通モジュールのパッケージが、起動クラスのパッケージの下にあるか（com.example.common と com.example.demo は横の関係）

原因3：MyBatis の Mapper が登録されない

MyBatis の Mapper（SQL を呼ぶインターフェース）は、@Mapper を付けるか @MapperScan で場所を教えないと登録されません。 MyBatis Spring Boot Starter 4.1.0 のソースでは、自動の探索は次の動きでした。

• 起動クラスと同じ範囲（Spring Boot の自動設定パッケージ）を探す
• 探すのは @Mapper が付いたインターフェースだけ
• @MapperScan などで Mapper が登録済みなら、自動の探索はしない

// 方法1：1つずつ @Mapper を付ける
@Mapper
public interface UserMapper {
    User findById(long id);
}

// 方法2：起動クラスか設定クラスで、まとめて場所を指定する
@SpringBootApplication
@MapperScan("com.example.demo.mapper")
public class DemoApplication { … }

Mapper のエラーの手前に DataSource のエラーが出ていないかも見ます。 DataSource の失敗は「Failed to configure a DataSource」として別に表示されます。MyBatis の書き方は、関連記事「MyBatis使い方｜Spring Boot連携と動的SQLタグ全実例」で扱っています。

原因4：@ConditionalOn… の条件で作られなかった

@ConditionalOnProperty・@ConditionalOnClass・@ConditionalOnBean などが付いた Bean は、条件を満たさないと作られません。 自分で書いた設定でも、Spring Boot の自動設定でも同じです。

@Configuration
public class MailConfig {

    @Bean
    @ConditionalOnProperty(name = "app.mail.enabled", havingValue = "true")
    MailClient mailClient() { … }
}

このとき application.yml に app.mail.enabled: true が無いと、MailClient は作られません。Description には「candidates were found but could not be injected」と、条件の結果が出ます。

どの自動設定が効いて、どれが外れたかを一覧で見るには、--debug を付けて起動します。 リファレンスによると、主なロガーがデバッグになり、条件の一覧（CONDITIONS EVALUATION REPORT）がコンソールに出ます。

java -jar app.jar --debug

application.yml に debug: true と書いても同じ一覧が出ます。一覧の「Negative matches」に、外れた自動設定と理由が並びます。

原因5：プロファイルが違う

@Profile("prod") が付いたクラスは、prod プロファイルで起動したときだけ登録されます。 ローカルで local プロファイルのまま起動すると、そのクラスが無い状態になります。

@Service
@Profile("prod")
public class SmtpMailClient implements MailClient { … }

この場合、条件付き Bean と違って「candidates were found」は出ず、ただの「could not be found」になります。X の実装クラスに @Profile が付いていないかを検索して確かめます。

対処は2つです。

• 起動時のプロファイルを合わせる（--spring.profiles.active=prod など）
• すべてのプロファイルで何かしらの実装が登録されるようにする（@Profile("!prod") の代替実装を用意する）

プロファイルの指定方法と優先順位は、関連記事「Spring Bootプロファイル切り替え｜application.ymlと優先順位」で扱っています。

原因6：インターフェースの実装が無い・2つある

実装が無い

OrderService がインターフェースで、実装クラスをまだ書いていない、または実装クラスに注釈が無い場合、このエラーになります。原因1と同じく、実装クラスに @Service を付けます。

実装が2つある（別のエラーになる）

実装が2つ以上あると、「見つからない」ではなく「1つに決められない」という別のエラーになります。

***************************
APPLICATION FAILED TO START
***************************

Description:

Parameter 0 of constructor in com.example.demo.user.UserService required a single bean, but 2 were found:
    - smtpMailClient: defined in file [/…/SmtpMailClient.class]
    - sesMailClient: defined in file [/…/SesMailClient.class]

This may be due to missing parameter name information

Action:

Consider marking one of the beans as @Primary, updating the consumer to accept multiple beans, or using @Qualifier to identify the bean that should be consumed

Ensure that your compiler is configured to use the '-parameters' flag.
You may need to update both your build tool settings as well as your IDE.
(See https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-6.1-Release-Notes#parameter-name-retention)

上は Spring Boot 4.1.1 の NoUniqueBeanDefinitionFailureAnalyzer の書式から組み立てた表示です（ファイルのパスは省略）。中身の例外は NoUniqueBeanDefinitionException で、原文は expected single matching bean but found 2: smtpMailClient,sesMailClient の形です。

1つに決める方法は3つです。

// 1. どちらかを既定にする
@Service
@Primary
public class SmtpMailClient implements MailClient { … }

// 2. 受け取る側で名前を指定する
public UserService(@Qualifier("sesMailClient") MailClient mailClient) { … }

// 3. 全部受け取る
public UserService(List<MailClient> mailClients) { … }

@Qualifier の名前を書き間違えると、今度は「could not be found」に戻ります。 そのときは Description に The injection point has the following annotations: と @Qualifier("…") が出ます。Bean の名前は、クラス名の先頭を小文字にしたもの（SesMailClient → sesMailClient）が既定です。

「This may be due to missing parameter name information」は、引数名で Bean を選べなかった可能性を示す追記です。Spring Framework 6.1 以降は、引数名で選ぶにはコンパイル時の -parameters が必要です。Spring Boot の Gradle プラグインと spring-boot-starter-parent は、ドキュメントによるとコンパイルに -parameters を付けます。

原因7：@WebMvcTest のテストで足りない

アプリは起動するのに、テストだけでこのエラーが出るときは、@WebMvcTest が原因のことが多いです。 @WebMvcTest は、Web 層（コントローラーなど）だけを登録して速く起動するための注釈です。リファレンスによると、@Component・@Service などの普通の Bean は登録されません。

Spring Boot 4.1.1 のソース（WebMvcTypeExcludeFilter）で、登録される種類は次のとおりでした。

コントローラーが OrderService を受け取る場合、テスト側で代わりのモックを置きます。Spring Boot 4 では、Spring Framework の @MockitoBean を使います。

import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.test.context.bean.override.mockito.MockitoBean;

@WebMvcTest(OrderController.class)
class OrderControllerTest {

    @Autowired
    MockMvc mockMvc;

    @MockitoBean
    OrderService orderService;   // ← これが無いと required a bean of type 'OrderService'

    @Test
    void 一覧を返す() throws Exception {
        given(orderService.findAll()).willReturn(List.of());
        mockMvc.perform(get("/orders")).andExpect(status().isOk());
    }
}

Spring Boot 4 では @WebMvcTest のパッケージが org.springframework.boot.webmvc.test.autoconfigure に変わっています。テストの書き方の全体は、関連記事「Spring Bootテスト入門｜@WebMvcTestとMockMvcの使い分け」で扱っています。

そのほかの原因

ジェネリクスの違いは見落としやすい原因です。 Spring は Repository<Order> と Repository<User> を別の型として扱います。一方で、Boot の表示は型引数を除いたクラス名だけを出します（ソースで getRawClass() を使っていました）。

@Component
class UserRepository implements Repository<User> { … }

// Repository<Order> を受け取ろうとすると、
// 表示は required a bean of type 'com.example.demo.Repository' となり、
// 「Repository の Bean はあるのに」と迷いやすい
public OrderService(Repository<Order> repository) { … }

直す順番のチェックリスト

1. Description の '…' の中の型を確かめる（受け取る側ではなく、受け取られる側）
2. その型のクラスを開く。インターフェースなら実装クラスを探す
3. 実装クラスに @Service・@Component などがあるか
4. 実装クラスのパッケージが、起動クラスのパッケージの下にあるか
5. @Profile・@ConditionalOn… が付いていないか
6. Description に「candidates were found」があれば、not loaded because の後ろを読む
7. テストだけで出るなら、@WebMvcTest などのスライステストかを確かめる
8. それでも分からなければ --debug で条件の一覧を出す

よくある質問

Q. @Autowired を付けたのにエラーが出ます。 A. @Autowired は「受け取る」側の印です。このエラーは「渡す Bean が無い」ことが原因なので、受け取られるクラスの登録（注釈・パッケージ・条件）を確かめます。コンストラクタが1つだけなら @Autowired は省略できます。注入の書き方は、関連記事「Spring DIとは｜@Autowiredとコンストラクタインジェクション」で扱っています。

Q. IntelliJ IDEA では警告が出ないのに、起動するとエラーになります。 A. IDE の判定と、実際の起動時の判定は一致しないことがあります。プロファイルや @ConditionalOn… は起動時の設定で決まるため、起動時の Description を正として調べます。

Q. 必須でない Bean を、無ければ無いで動かしたいです。 A. 受け取る側を ObjectProvider<MailClient> や Optional<MailClient> にすると、Bean が無くても起動します。ObjectProvider の getIfAvailable() で、あれば使う書き方ができます。

Q. Field xxx in yyy required a bean … と出ます。コンストラクタのときと違いはありますか。 A. 原因と直し方は同じです。書き出しが Field なら @Autowired のフィールド、Parameter 0 of constructor ならコンストラクタの引数で受け取ろうとしています。

Q. 自動設定を除外する設定がどこにあるか分かりません。 A. @SpringBootApplication(exclude = …) と、application.yml の spring.autoconfigure.exclude の2か所を検索します。設定キーの一覧は関連記事「Spring Boot application.properties設定一覧」で扱っています。

まとめ

• 受け取られる側の型 X の Bean が1つも無いときのエラー。中身は NoSuchBeanDefinitionException
• Description の1文目で受け取る場所、'…' の中で足りない型が分かる
• 多い原因は注釈の付け忘れ・起動クラスより外のパッケージ・@Mapper 漏れ・条件・プロファイル
• 「candidates were found but could not be injected」が出たら、not loaded because の後ろが答え
• 実装が2つあるときは別のエラー（required a single bean, but 2 were found）。@Primary・@Qualifier で1つに決める
• テストだけで出るなら @WebMvcTest は @Service を登録しないので @MockitoBean を置く

参考・出典

確認日はいずれも 2026年10月12日です。

• Spring Boot リファレンス「Structuring Your Code」：https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html
• Spring Boot リファレンス「Auto-configuration」：https://docs.spring.io/spring-boot/reference/using/auto-configuration.html
• Spring Boot リファレンス「Testing Spring Boot Applications」：https://docs.spring.io/spring-boot/reference/testing/spring-boot-applications.html
• Spring Boot ソースコード（v4.1.1）NoSuchBeanDefinitionFailureAnalyzer：https://github.com/spring-projects/spring-boot/blob/v4.1.1/core/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/diagnostics/analyzer/NoSuchBeanDefinitionFailureAnalyzer.java
• Spring Boot ソースコード（v4.1.1）NoUniqueBeanDefinitionFailureAnalyzer：https://github.com/spring-projects/spring-boot/blob/v4.1.1/core/spring-boot/src/main/java/org/springframework/boot/diagnostics/analyzer/NoUniqueBeanDefinitionFailureAnalyzer.java
• Spring Framework ソースコード（v7.0.9）DefaultListableBeanFactory：https://github.com/spring-projects/spring-framework/blob/v7.0.9/spring-beans/src/main/java/org/springframework/beans/factory/support/DefaultListableBeanFactory.java
• MyBatis Spring Boot Starter「Introduction」：https://mybatis.org/spring-boot-starter/mybatis-spring-boot-autoconfigure/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。