jeecgboot/JeecgBoot · error · JeecgBootException

上传失败，存在非法文件类型：{suffix}

Error message

上传失败，存在非法文件类型：{suffix}

What it means

Thrown by SsrfFileTypeFilter.checkUploadFileType after validatePathSecurity passes but the detected file suffix (from getFileType, which combines extension + magic-header check) is not in FILE_TYPE_WHITE_LIST. This is the upload-side deny-by-default whitelist that prevents uploading executable/unsafe types.

Source

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

    public static void checkUploadFileType(MultipartFile file) throws Exception {
        checkUploadFileType(file, null);
    }
    
    /**
     * 上传文件类型过滤
     *
     * @param file
     */
    public static void checkUploadFileType(MultipartFile file, String customPath) throws Exception {
        //1. 路径安全校验
        validatePathSecurity(customPath);
        //2. 校验文件后缀和头
        String suffix = getFileType(file, customPath);
        log.info("【文件上传校验】文件后缀 suffix: {}，customPath：{}", suffix, customPath);
        boolean isAllowExtension = FILE_TYPE_WHITE_LIST.contains(suffix.toLowerCase());
        //是否允许下载的文件
        if (!isAllowExtension) {
            throw new JeecgBootException("上传失败，存在非法文件类型：" + suffix);
        }
    }

    /**
     * 通过读取文件头部获得文件类型
     *
     * @param file
     * @return 文件类型
     * @throws Exception
     */

    private static String getFileType(MultipartFile file, String customPath) throws Exception {
        // 代码逻辑说明: [issue/4672]方法造成的文件被占用，注释掉此方法tomcat就能自动清理掉临时文件
        String fileExtendName = null;
        InputStream is = null;
        try {
            //is = new FileInputStream(file);
            is = file.getInputStream();

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. If the file type is legitimate, add its extension to FILE_TYPE_WHITE_LIST after a security review.
2. Have the user convert the file to a whitelisted type before uploading.
3. Verify the file's actual content type matches its extension — re-export the file cleanly.
4. Do not loosen the whitelist to accept executable/script types; serve those out-of-band instead.

Example fix

// before
// whitelist = [jpg,png,pdf,xlsx]
upload.resume.docx  // -> 上传失败，存在非法文件类型

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

String suffix = FilenameUtils.getExtension(file.getOriginalFilename()).toLowerCase();
if (!FILE_TYPE_WHITE_LIST.contains(suffix)) reject();

public static boolean uploadAllowed(MultipartFile f){
    String s = FilenameUtils.getExtension(f.getOriginalFilename()).toLowerCase();
    return FILE_TYPE_WHITE_LIST.contains(s);
}

try { SsrfFileTypeFilter.checkUploadFileType(file, customPath); }
catch (Exception e) { result.error500(e.getMessage()); }

When it happens

Trigger: Uploading a file whose extension is not whitelisted (.jsp, .sh, .exe, .html), a file whose header magic does not match its claimed extension (polyglot detection), or a file with a double extension where the resolved type is blocked.

Common situations: User uploads a document format the system was not configured to accept; an attacker disguises an executable with an image extension; whitelist was tightened by a security patch and old file types now fail.

Related errors

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

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