apache/dolphinscheduler · error · AlertEmailException

receivers must not be null

Error message

receivers must not be null

What it means

The MailSender constructor requires the configuration key PLUGIN_DEFAULT_EMAIL_RECEIVERS. If it is absent or an empty string, it throws AlertEmailException('receivers must not be null') during alert plugin initialization.

Solutions

  1. Open the email alert instance settings in DolphinScheduler and set the Receivers field (comma-separated addresses).
  2. Ensure the alert plugin params JSON contains PLUGIN_DEFAULT_EMAIL_RECEIVERS with a non-empty value.
  3. Re-create the alert instance if the parameter was lost during upgrade.

Example fix

// before
{"xlsx.file.path":"/tmp/xls", "mail.protocol":"SMTP"} // no receivers
// after
{"xlsx.file.path":"/tmp/xls", "receivers":"ops@example.com,dev@example.com"}
Defensive patterns

Strategy: validation

Validate before calling

java.util.Map<String,String> cfg = ...;
Object r = cfg.get("receivers");
if (r == null || r.toString().trim().isEmpty()) throw new IllegalArgumentException("receivers required");

Try / catch

try { new MailSender(config); } catch (AlertEmailException e) { /* prompt user to fill receivers */ }

Prevention

When it happens

Trigger: Creating MailSender with a config map lacking 'receivers' or with 'receivers' set to ''.

Common situations: Email alert instance created in the UI without filling the Receivers field; alert parameters JSON missing the receivers key after an upgrade or manual edit.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/4a3f31ec7181cdfe. Report an issue: GitHub.

Appendix: source

Thrown at dolphinscheduler-alert/dolphinscheduler-alert-plugins/dolphinscheduler-alert-email/src/main/java/org/apache/dolphinscheduler/plugin/alert/email/MailSender.java:86

    private final String mailProtocol = "SMTP";
    private final String mailSmtpHost;
    private final String mailSmtpPort;
    private final String mailSenderEmail;
    private final String enableSmtpAuth;
    private final String mailUser;
    private final String mailPasswd;
    private final String mailUseStartTLS;
    private final String mailUseSSL;
    private final String sslTrust;
    private final String showType;
    private final AlertTemplate alertTemplate;
    private final String mustNotNull = " must not be null";
    private String xlsFilePath;

    MailSender(Map<String, String> config) {
        String receiversConfig = config.get(MailParamsConstants.NAME_PLUGIN_DEFAULT_EMAIL_RECEIVERS);
        if (receiversConfig == null || "".equals(receiversConfig)) {
            throw new AlertEmailException(MailParamsConstants.NAME_PLUGIN_DEFAULT_EMAIL_RECEIVERS + mustNotNull);
        }

        receivers = Arrays.asList(receiversConfig.split(","));

        String receiverCcsConfig = config.get(MailParamsConstants.NAME_PLUGIN_DEFAULT_EMAIL_RECEIVERCCS);

        receiverCcs = new ArrayList<>();
        if (receiverCcsConfig != null && !"".equals(receiverCcsConfig)) {
            receiverCcs.addAll(Arrays.asList(receiverCcsConfig.split(",")));
        }

        mailSmtpHost = config.get(MailParamsConstants.NAME_MAIL_SMTP_HOST);
        requireNonNull(mailSmtpHost, MailParamsConstants.NAME_MAIL_SMTP_HOST + mustNotNull);

        mailSmtpPort = config.get(MailParamsConstants.NAME_MAIL_SMTP_PORT);
        requireNonNull(mailSmtpPort, MailParamsConstants.NAME_MAIL_SMTP_PORT + mustNotNull);

        mailSenderEmail = config.get(MailParamsConstants.NAME_MAIL_SENDER);

View on GitHub (pinned to 02eac45a1b)