What causes "导入Excel校验失败！" in jeecgboot/JeecgBoot?

Re-download the official SysDict import template from the dict management page and fill only its columns.

jeecgboot/JeecgBoot · warning · RuntimeException

导入Excel校验失败！

Error message

导入Excel校验失败 ！

What it means

During SysDict Excel import, ExcelImportCheckUtil.check computes how well the uploaded workbook's header rows match the SysDictPage fields. When the match probability is too low (returns false), the file is judged not to be a valid SysDict import template and a RuntimeException is thrown, aborting the import before AutoPoi tries to parse it.

Source

Thrown at jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/controller/SysDictController.java:673

	 * @return
	 */
    @RequiresPermissions("system:dict:importExcel")
	@RequestMapping(value = "/importExcel", method = RequestMethod.POST)
	public Result<?> importExcel(HttpServletRequest request, HttpServletResponse response) {
 		MultipartHttpServletRequest multipartRequest = (MultipartHttpServletRequest) request;
		Map<String, MultipartFile> fileMap = multipartRequest.getFileMap();
		for (Map.Entry<String, MultipartFile> entity : fileMap.entrySet()) {
            // 获取上传文件对象
			MultipartFile file = entity.getValue();
			ImportParams params = new ImportParams();
			params.setTitleRows(2);
			params.setHeadRows(2);
			params.setNeedSave(true);
			try {
				//导入Excel格式校验，看匹配的字段文本概率
				Boolean t = ExcelImportCheckUtil.check(file.getInputStream(), SysDictPage.class, params);
				if(t!=null && !t){
					throw new RuntimeException("导入Excel校验失败 ！");
				}
				List<SysDictPage> list = ExcelImportUtil.importExcel(file.getInputStream(), SysDictPage.class, params);
				// 错误信息
				List<String> errorMessage = new ArrayList<>();
				int successLines = 0, errorLines = 0;
				for (int i=0;i< list.size();i++) {
					SysDict po = new SysDict();
					BeanUtils.copyProperties(list.get(i), po);
					po.setDelFlag(CommonConstant.DEL_FLAG_0);
					try {
						Integer integer = sysDictService.saveMain(po, list.get(i).getSysDictItemList());
						if(integer>0){
							successLines++;
                        // 代码逻辑说明: [JTC-1168]如果字典项值为空，则字典项忽略导入------------
						}else if(integer == -1){
                            errorLines++;
                            errorMessage.add("字典名称：" + po.getDictName() + "，对应字典列表的字典项值不能为空，忽略导入。");
                        }else{

View on GitHub (pinned to 96fb33f5ec)

Solutions

Re-download the official SysDict import template from the dict management page and fill only its columns.
Confirm the header layout matches (2 title rows, 2 head rows) and column names align with SysDictPage.
If the file is genuinely a dict template but still rejected, verify the SysDictPage field set matches this build's version.

Example fix

// before: importing an arbitrary workbook
MultipartFile f = userFile; // wrong template
// after: validate against the official template before upload, or
// catch the failure and report the expected columns to the user
try {
    Boolean ok = ExcelImportCheckUtil.check(f.getInputStream(), SysDictPage.class, params);
    if (ok != null && !ok) return Result.error("请使用系统下载的字典导入模板");
} catch (Exception ex) { return Result.error("模板读取失败: " + ex.getMessage()); }

Defensive patterns

Strategy: validation

Validate before calling

// Client/server pre-check: confirm the workbook looks like a SysDict template before importing.
Boolean ok = ExcelImportCheckUtil.check(file.getInputStream(), SysDictPage.class, params);
if (ok != null && !ok) {
    return Result.error("请使用系统下载的字典导入模板");
}

Try / catch

try {
    return sysDictController.importExcel(request);
} catch (RuntimeException e) {
    if ("导入Excel校验失败 ！".equals(e.getMessage())) {
        return Result.error("Excel 模板不匹配, 请下载最新模板后重试");
    }
    throw e;
}

Prevention

Always import from the template downloaded from the same JeecgBoot version.
Lock the header rows (titleRows=2, headRows=2) so users cannot shift them.
Reject non-.xlsx uploads at the controller before reaching the check.

When it happens

Trigger: Uploading an Excel whose columns do not match SysDictPage fields; uploading an unrelated report; using a template from an older/newer JeecgBoot version whose SysDictPage columns differ; a non-xlsx file renamed to .xlsx.

Common situations: User downloaded the wrong template; template version drift after an upgrade; manual edits shifted the two title rows (titleRows=2, headRows=2) out of alignment.

Related errors

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

导入Excel校验失败 ！