{"record":{"id":"2df6edb7421f0e47","repo":"apache/dolphinscheduler","slug":"create-xlsx-directory-error","errorCode":null,"errorMessage":"Create xlsx directory error","messagePattern":"Create xlsx directory error","errorType":"exception","errorClass":"AlertEmailException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-alert/dolphinscheduler-alert-plugins/dolphinscheduler-alert-email/src/main/java/org/apache/dolphinscheduler/plugin/alert/email/ExcelUtils.java","lineNumber":60,"sourceCode":"public final class ExcelUtils {\n\n    private static final int XLSX_WINDOW_ROW = 10000;\n    private ExcelUtils() {\n        throw new UnsupportedOperationException(\"This is a utility class and cannot be instantiated\");\n    }\n\n    /**\n     * generate excel file\n     *\n     * @param content the content\n     * @param title the title\n     * @param xlsFilePath the xls path\n     */\n    static void genExcelFile(String content, String title, String xlsFilePath) {\n        File file = new File(xlsFilePath);\n        if (!file.exists() && !file.mkdirs()) {\n            log.error(\"Create xlsx directory error, path:{}\", xlsFilePath);\n            throw new AlertEmailException(\"Create xlsx directory error\");\n        }\n\n        List<LinkedHashMap> itemsList = JSONUtils.toList(content, LinkedHashMap.class);\n\n        if (CollectionUtils.isEmpty(itemsList)) {\n            log.error(\"itemsList is null\");\n            throw new AlertEmailException(\"itemsList is null\");\n        }\n\n        LinkedHashMap<String, Object> headerMap = itemsList.get(0);\n\n        List<String> headerList = new ArrayList<>();\n\n        for (Map.Entry<String, Object> en : headerMap.entrySet()) {\n            headerList.add(en.getKey());\n        }\n        try (\n                SXSSFWorkbook wb = new SXSSFWorkbook(XLSX_WINDOW_ROW);","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-alert/dolphinscheduler-alert-plugins/dolphinscheduler-alert-email/src/main/java/org/apache/dolphinscheduler/plugin/alert/email/ExcelUtils.java#L42-L78","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix permissions on the directory intended to hold the xlsx file (chown/chmod for the alert-server user).","Correct the xlsFilePath configuration so it points inside an existing writable directory, not at an existing file.","Ensure parent directories of the path exist and are real directories.","Check disk space / read-only mount on the alert server host."],"exampleFix":"// before\nmailAlertXlsFilePath=/opt/ds/alert/xlsx/file.xls // parent exists as file or not writable\n// after\nsudo mkdir -p /opt/ds/alert/xlsx && sudo chown dsuser:dsuser /opt/ds/alert/xlsx\nmailAlertXlsFilePath=/opt/ds/alert/xlsx","handlingStrategy":"validation","validationCode":"java.io.File dir = new java.io.File(xlsFilePath);\nif (!dir.isDirectory() && !dir.mkdirs()) { throw new IllegalStateException(\"cannot create dir: \" + xlsFilePath); }","typeGuard":"boolean isWritableDir(String p) { java.io.File f = new java.io.File(p); return f.isDirectory() && f.canWrite(); }","tryCatchPattern":"try { ExcelUtils.genExcelFile(content, title, xlsFilePath); } catch (AlertEmailException e) { log.error(\"excel gen failed for {}\", xlsFilePath, e); }","preventionTips":["Configure the xlsx path to an existing, writable directory for the alert-server user","Check mount options (not read-only) in containerized deployments","Monitor disk space on the alert server"],"tags":["filesystem","io","alert-email"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}