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.

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)

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"}

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

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

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

• url can not be null
• headerParams is not a valid json
• bodyParams is not a valid json
• requestType is not a valid value
• Failed to construct OIDC redirect URI

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