Improve MailSender related error message when the mail starter is used

[odrotbohm]

The spring-boot-starter-mail starter sets up autoconfiguration to declare a MailSender bean if fundamental mail-related properties are configured. If you declare the starter as described in the reference documentation and declare a dependency to a MailSender the application still fails because no bean of that type can be found.

It would be nice if:

• The error message hinted at the fact that it's enough to configure the mail-related properties over asking the users to declare a bean themselves.
• The reference documentation mentioned that, too.

[snicoll]

If you declare the starter as described in the reference documentation and declare a dependency to a MailSender the application still fails

I am not sure I got that as it follows with "it would be nice if". How does it fail? Can you share a small sample?

[odrotbohm]

… still fails because no bean of that type can be found.

Example attached below.

1. Run the app…

2026-03-02T09:35:08.533+01:00 ERROR 24161 --- [mail-example] [           main] o.s.b.d.LoggingFailureAnalysisReporter   : 

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

Description:

Parameter 0 of method runner in example.MailExampleApplication required a bean of type 'org.springframework.mail.MailSender' that could not be found.


Action:

Consider defining a bean of type 'org.springframework.mail.MailSender' in your configuration.

2. Uncomment the smtp.mail.server property in application.properties > application works.

It would be nice if the error message and docs hinted at that way of solving the problem.

example.zip

[snicoll]

I am still confused. The reference guide currently is:

If spring.mail.host and the relevant libraries (as defined by spring-boot-starter-mail) are available, a default JavaMailSender is created if none exists.

What hint do you need in the doc?

If you want to understand why the auto-configuration did not produce a bean as you expect, the auto-configuration report is what you should be reviewing.

MailSenderAutoConfiguration:
      Did not match:
         - AnyNestedCondition 0 matched 2 did not; NestedCondition on MailSenderAutoConfiguration.MailSenderCondition.JndiNameProperty @ConditionalOnProperty (spring.mail.jndi-name) did not find property 'spring.mail.jndi-name'; NestedCondition on MailSenderAutoConfiguration.MailSenderCondition.HostProperty @ConditionalOnProperty (spring.mail.host) did not find property 'spring.mail.host' (MailSenderAutoConfiguration.MailSenderCondition)
      Matched:
         - @ConditionalOnClass found required classes 'jakarta.mail.internet.MimeMessage', 'jakarta.activation.MimeType', 'org.springframework.mail.MailSender' (OnClassCondition)

[odrotbohm]

I must have missed that in the docs. It would still be nice if the error message was better so that I don't have to wonder why the bean is not there.

Currently, a user not familiar with the defaults and their constraints will have to enable debug logging and then skim over the long list of autoconfigurations to find the actual problem at the very end of the line. An error message mentioning the property would prevent the user from having to go through this process.

Fundamentally, the starter exists to not have to declare the bean itself. That's why I think its presence should guide the user towards using it as intended, which is by declaring the properties.

[wilkinsona]

This feels to me somewhat similar to what we do for a DataSource when we can't auto-configure one. We throw a specific exception that's then analysed to guide the user towards settings things up properly. This case isn't exactly the same (as the auto-configuration is backing off rather than failing) but this leads to a more general failure due to a missing bean and, crucially, some misleading guidance that's pointing in the wrong direction. It would be better if the end result was more like the DataSource case and we were able to provide more specific and more accurate guidance to the user.

Taking a bit of a step back, I think the modularization in 4.0 has created an oppourtunity for us to review things like this and see if there's an opportunity to be more helpful. Post-modularization, the classpath provides a much stronger signal about the user's intent. In this particular case, I think it would be reasonable for us to assume that the presence of spring-boot-mail means that the user wants a MailSender to be auto-configured. I'm not sure how we'd get there from where we are now, but it could be argued that failing fast without the necessary property would result in a better OotB experience.

I'd like to discuss this with the rest of the team as I think there are a few different ways forward, including:

1. Add some specific failure analysis to spring-boot-mail when something tries to inject a MailSender and there's no such bean
2. Do something more general purpose in the existing failure analysis for a missing bean that points to the auto-configuration report
3. Change the behavior to fail fast when spring-boot-mail is on the classpath but it isn't doing anything due to some other prerequisites not being in place

Option 3 could also be considered more broadly as I suspect we may have other modules that won't do anything without some other configuration being in place.

[odrotbohm]

I had naively hoped that a Boot-specific error reporter functionality (I forgot the name of the interface) could be registered by the spring-boot-mail artifact that would handle a NoSuchBeanDefinition for MailSender by recommending the property or defining a custom bean. I guess that's your option one.