apache/dolphinscheduler · error · AlertEmailException

Create xlsx directory error

Error message

Create xlsx directory error

What it means

ExcelUtils.genExcelFile creates a File at xlsFilePath and, if it does not exist, attempts mkdirs(). When directory creation fails (permissions, invalid path, or a parent is actually a regular file), it throws AlertEmailException('Create xlsx directory error'). This runs inside the email alert plugin while generating the Excel attachment for an alert.

Source

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

public final class ExcelUtils {

    private static final int XLSX_WINDOW_ROW = 10000;
    private ExcelUtils() {
        throw new UnsupportedOperationException("This is a utility class and cannot be instantiated");
    }

    /**
     * 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);

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Fix permissions on the directory intended to hold the xlsx file (chown/chmod for the alert-server user).
2. Correct the xlsFilePath configuration so it points inside an existing writable directory, not at an existing file.
3. Ensure parent directories of the path exist and are real directories.
4. Check disk space / read-only mount on the alert server host.

Example fix

// before
mailAlertXlsFilePath=/opt/ds/alert/xlsx/file.xls // parent exists as file or not writable
// after
sudo mkdir -p /opt/ds/alert/xlsx && sudo chown dsuser:dsuser /opt/ds/alert/xlsx
mailAlertXlsFilePath=/opt/ds/alert/xlsx

java.io.File dir = new java.io.File(xlsFilePath);
if (!dir.isDirectory() && !dir.mkdirs()) { throw new IllegalStateException("cannot create dir: " + xlsFilePath); }

boolean isWritableDir(String p) { java.io.File f = new java.io.File(p); return f.isDirectory() && f.canWrite(); }

try { ExcelUtils.genExcelFile(content, title, xlsFilePath); } catch (AlertEmailException e) { log.error("excel gen failed for {}", xlsFilePath, e); }

When it happens

Trigger: genExcelFile is called with an xlsFilePath that cannot be created: the parent directory is not writable, the path's parent exists as a regular file, the path is invalid for the OS, or the disk is full/read-only.

Common situations: Alert server running as a user without write permission to the configured xlsx file path; misconfigured mail alert 'xlsx path' parameter pointing at an existing file instead of a directory; container with read-only filesystem.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• generate excel error
• Failed to create parent directory for destination file
• itemsList is null
• Update the resource file from content: {fileAbsolutePath} fa
• Download the resource file: {fileAbsolutePath} failed

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