halo-dev/halo · error · ServerWebInputException

Failed to send email, please check your email configuration.

Error message

Failed to send email, please check your email configuration.

What it means

Thrown as ServerWebInputException (HTTP 400) by EmailConfigValidationEndpoint.verifyEmailSenderConfig when mailSender.send(message) throws a MailException. The endpoint performs a live test send to the current user's email; any SMTP-level failure is wrapped into a bad-input response (the underlying cause is logged at error level).

Source

Thrown at application/src/main/java/run/halo/app/notification/endpoint/EmailConfigValidationEndpoint.java:78

                                .requestBody(
                                        requestBodyBuilder().required(true).implementation(ValidationRequest.class))
                                .response(responseBuilder().implementation(Void.class)))
                .build();
    }

    private Mono<ServerResponse> verifyEmailSenderConfig(ServerRequest request) {
        return request.bodyToMono(ValidationRequest.class)
                .switchIfEmpty(Mono.error(new ServerWebInputException("Required request body is missing.")))
                .flatMap(validationRequest -> getCurrentUserEmail().flatMap(recipient -> {
                    var mailSender = emailSenderHelper.createJavaMailSender(validationRequest);
                    var message = emailSenderHelper.createMimeMessagePreparator(
                            validationRequest, recipient, EMAIL_SUBJECT, EMAIL_BODY, EMAIL_BODY);
                    try {
                        mailSender.send(message);
                    } catch (MailException e) {
                        String errorMsg = "Failed to send email, please check your email configuration.";
                        log.error(errorMsg, e);
                        throw new ServerWebInputException(errorMsg, null, e);
                    }
                    return ServerResponse.ok().build();
                }));
    }

    Mono<String> getCurrentUserEmail() {
        return ReactiveSecurityContextHolder.getContext()
                .map(SecurityContext::getAuthentication)
                .map(Principal::getName)
                .flatMap(username -> client.fetch(User.class, username))
                .flatMap(user -> {
                    var email = user.getSpec().getEmail();
                    if (StringUtils.isBlank(email)) {
                        return Mono.error(
                                new ServerWebInputException("Your email is missing, please set it in your profile."));
                    }
                    return Mono.just(email);
                });

View on GitHub (pinned to d2f5165f9c)

Solutions

Open the server error log: the wrapped MailException shows the exact SMTP failure (auth, connect, cert).
Correct the SMTP host, port, username, password and the encryption mode (SSL/TLS vs STARTTLS).
Verify outbound network connectivity and DNS resolution from the Halo host to the SMTP server.
Use app-specific credentials (e.g. Gmail/O365 app password) where plain passwords are disabled.

Example fix

# before
spring.mail.host=smtp.example.com
spring.mail.port=25
spring.mail.username=user
spring.mail.password=oldpass

# after
spring.mail.host=smtp.example.com
spring.mail.port=587
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.username=user
spring.mail.password=newAppPassword

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight SMTP settings without sending (best-effort)
if (!StringUtils.hasText(smtpHost) || port <= 0) {
    throw new ServerWebInputException("SMTP host and port are required");
}

Try / catch

try {
    mailSender.send(message);
} catch (MailException e) {
    log.error("SMTP send failed", e);
    throw new ServerWebInputException("Failed to send email, please check your email configuration.", null, e);
}

Prevention

Validate SMTP host/port/credentials shape before test-send.
Match the encryption mode (SSL vs STARTTLS) to the provider's requirement.
Use app passwords for providers that disable basic auth.
Read the logged MailException root cause before changing config.

When it happens

Trigger: POST /apis/api.console.halo.run/v1alpha1/notifiers/default-email-notifier/verify-connection with an SMTP config that cannot deliver: wrong host/port, auth failure, TLS/SSL mismatch, blocked by firewall, or the recipient address rejected.

Common situations: Incorrect SMTP host/port/username/password in the notifier config; SMTP requires SSL but config uses STARTTLS (or vice versa); firewall blocking outbound 25/465/587; sender credentials revoked; recipient email invalid/unverified.

Related errors

AI-assisted analysis of halo-dev/halo@d2f5165f9c (2026-08-14). Data as JSON: /api/errors/94713d8f7efdcb82. Report an issue: GitHub.