apache/dolphinscheduler · error · AlertEmailException

itemsList is null

Error message

itemsList is null

What it means

After parsing the alert content JSON with JSONUtils.toList, genExcelFile checks whether the resulting list is empty and throws AlertEmailException('itemsList is null') when it is. The Excel attachment cannot be built without at least one row of data.

Source

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

    /**
     * generate excel file
     *
     * @param content the content
     * @param title the title
     * @param xlsFilePath the xls path
     */
    static void genExcelFile(String content, String title, String xlsFilePath) {
        File file = new File(xlsFilePath);
        if (!file.exists() && !file.mkdirs()) {
            log.error("Create xlsx directory error, path:{}", xlsFilePath);
            throw new AlertEmailException("Create xlsx directory error");
        }

        List<LinkedHashMap> itemsList = JSONUtils.toList(content, LinkedHashMap.class);

        if (CollectionUtils.isEmpty(itemsList)) {
            log.error("itemsList is null");
            throw new AlertEmailException("itemsList is null");
        }

        LinkedHashMap<String, Object> headerMap = itemsList.get(0);

        List<String> headerList = new ArrayList<>();

        for (Map.Entry<String, Object> en : headerMap.entrySet()) {
            headerList.add(en.getKey());
        }
        try (
                SXSSFWorkbook wb = new SXSSFWorkbook(XLSX_WINDOW_ROW);
                FileOutputStream fos = new FileOutputStream(String.format("%s/%s.xlsx", xlsFilePath, title))) {
            // declare a workbook
            // generate a table
            Sheet sheet = wb.createSheet();
            Row row = sheet.createRow(0);
            // set the height of the first line
            row.setHeight((short) 500);

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Guard at the alert producer: only send email alerts with TABLE showType when there is result data.
2. Validate that the content string is a non-empty JSON array of objects before configuring the email alert.
3. Skip Excel attachment generation when the alert result set is empty.

Example fix

// before
List<LinkedHashMap> itemsList = JSONUtils.toList(content, LinkedHashMap.class);
// after
if (content == null || content.trim().isEmpty()) { return; } // skip empty alerts upstream
List<LinkedHashMap> itemsList = JSONUtils.toList(content, LinkedHashMap.class);

if (content == null || content.trim().isEmpty() || "[]".equals(content.trim())) { skipEmailAttachment(); }

boolean hasRows(String json) { List<?> l = JSONUtils.toList(json, Object.class); return l != null && !l.isEmpty(); }

try { ExcelUtils.genExcelFile(content, title, path); } catch (AlertEmailException e) { log.warn("empty/invalid alert content skipped", e); }

When it happens

Trigger: The alert 'content' passed to genExcelFile is null, not valid JSON, an empty JSON array, or JSON that deserializes to an empty list (e.g. empty alert result sets with empty showType data).

Common situations: Workflow finished with no result rows so the alert content is '[]' or empty string; upstream task produced malformed output that JSONUtils.toList silently converts to null; showType configured as TABLE but no data available.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• Create xlsx directory error
• generate excel error
• headerParams is not a valid json
• bodyParams is not a valid json
• ENVIRONMENT_WORKER_GROUPS_IS_INVALID

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