jeecgboot/JeecgBoot · error · JeecgBootException

下载失败，存在非法文件类型：{suffix}

Error message

下载失败，存在非法文件类型：{suffix}

What it means

Thrown by SsrfFileTypeFilter.checkDownloadFileType when the file's extension (lowercased) is not in FILE_TYPE_WHITE_LIST. This is a deny-by-default extension whitelist applied to download endpoints to stop retrieval of dangerous file types (jsp, exe, sh, etc.). Returns JeecgBootException.

Source

Thrown at jeecg-boot/jeecg-boot-base-core/src/main/java/org/jeecg/common/util/filter/SsrfFileTypeFilter.java:161

     */
    private static String getFileTypeBySuffix(String fileName) {
        return fileName.substring(fileName.lastIndexOf(".") + 1, fileName.length());
    }


    /**
     * 下载文件类型过滤
     *
     * @param filePath
     */
    public static void checkDownloadFileType(String filePath) throws IOException {
        //文件后缀
        String suffix = getFileTypeBySuffix(filePath);
        log.debug(" 【文件下载校验】文件后缀 suffix: {}", suffix);
        boolean isAllowExtension = FILE_TYPE_WHITE_LIST.contains(suffix.toLowerCase());
        //是否允许下载的文件
        if (!isAllowExtension) {
            throw new JeecgBootException("下载失败，存在非法文件类型：" + suffix);
        }
    }

    /**
     * 上传文件类型过滤
     *
     * @param file
     */
    public static void checkUploadFileType(MultipartFile file) throws Exception {
        checkUploadFileType(file, null);
    }
    
    /**
     * 上传文件类型过滤
     *
     * @param file
     */
    public static void checkUploadFileType(MultipartFile file, String customPath) throws Exception {

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Add the legitimate extension to FILE_TYPE_WHITE_LIST in SsrfFileTypeFilter (if the type is genuinely safe to serve).
2. Re-save or convert the file to a whitelisted type (e.g. rename .jpeg to .jpg if jpg is whitelisted).
3. Confirm the download URL references the intended file and not one with a stripped/doubled extension.
4. Audit the whitelist with security before expanding it — do not add executable types.

Example fix

// before
// FILE_TYPE_WHITE_LIST = [jpg, png, pdf]
// user requests report.jxls -> 下载失败，存在非法文件类型

// after (if approved)
FILE_TYPE_WHITE_LIST.add("jxls");

String suffix = filePath.substring(filePath.lastIndexOf('.')+1).toLowerCase();
if (!FILE_TYPE_WHITE_LIST.contains(suffix)) throw new IllegalArgumentException("not allowed");

public static boolean downloadAllowed(String path){
    String s = path.substring(path.lastIndexOf('.')+1).toLowerCase();
    return FILE_TYPE_WHITE_LIST.contains(s);
}

try { SsrfFileTypeFilter.checkDownloadFileType(path); }
catch (JeecgBootException e) { return ResponseEntity.badRequest().body(e.getMessage()); }

When it happens

Trigger: A download request (e.g. /sys/download, sys/files/download) for a file whose suffix is not whitelisted — .jsp, .sh, .bat, .exe, .war, .config, or a file with no extension. Also fires for case variants since the check lowercases the suffix.

Common situations: A user uploaded a file type the admin later removed from the whitelist; a migration imported legacy files with non-whitelisted extensions; an attacker probing for sensitive file downloads.

Related errors

• 上传失败，存在非法文件类型：{suffix}
• 上传业务路径包含非法字符！
• 表名不合法，存在SQL注入风险!--->{table}
• 字段不合法，存在SQL注入风险!--->{field}
• 上传业务路径深度超出限制！

AI-assisted analysis of jeecgboot/JeecgBoot@96fb33f5ec (2026-08-14). Data as JSON: /api/errors/fef6256789f507e5. Report an issue: GitHub.