jeecgboot/JeecgBoot · error · JeecgBootException

生成word文档失败，请检查模版和数据是否正确

Error message

生成word文档失败，请检查模版和数据是否正确

What it means

AigcWordTemplateServiceImpl.generateWordFromTpl() compiles a freshly-built template with poi-tl (XWPFTemplate.compile(...).render(data).write(...)). Any render or write exception is thrown as a JeecgBootException with a GENERIC message -- the cause is logged separately but not appended to the thrown text, so you must read the logs to learn why.

Source

Thrown at jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag/src/main/java/org/jeecg/modules/airag/wordtpl/service/impl/AigcWordTemplateServiceImpl.java:63

    WordTplUtils wordTplUtils;

    @Override
    public void generateWordFromTpl(WordTplGenDTO wordTplGenDTO, ByteArrayOutputStream wordOutputStream) {
        AssertUtils.assertNotEmpty("参数异常", wordTplGenDTO);
        AssertUtils.assertNotEmpty("模版ID不能为空", wordTplGenDTO.getTemplateId());
        String templateId = wordTplGenDTO.getTemplateId();
        // 生成word模版 date:2025/7/10
        AigcWordTemplate template = getById(templateId);
        ByteArrayOutputStream wordTemplateOut = new ByteArrayOutputStream();
        wordTplUtils.generateWordTemplate(template, wordTemplateOut);
        //根据word模版和数据生成word文件
        Map<String, Object> data = wordTplGenDTO.getData();
        mergeSystemVarsToData(data);
        try {
            XWPFTemplate.compile(new ByteArrayInputStream(wordTemplateOut.toByteArray())).render(data).write(wordOutputStream);
        }catch (Exception e){
            log.error(e.getMessage(), e);
            throw new JeecgBootException("生成word文档失败，请检查模版和数据是否正确");
        }

    }

    /**
     * 将系统变量合并到数据中
     *
     * @param data
     * @author chenrui
     * @date 2025/7/3 17:43
     */
    private static void mergeSystemVarsToData(Map<String, Object> data) {
        for (String key : SYSTEM_KEYS) {
            if (!data.containsKey(key)) {
                String value = JwtUtil.getUserSystemData(key, null);
                if (value != null) {
                    data.put(key, value);
                }

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Read the 'log.error(e.getMessage(), e)' line -- the thrown message carries no detail.
2. Diff the data map keys against the template placeholders.
3. Render locally with XWPFTemplate.compile(...).render(data) using the same template bytes to reproduce.
4. Confirm the poi-tl version supports the tag policy used.
5. Ensure a LoginUser context exists so mergeSystemVarsToData can resolve system vars.

Example fix

// before
catch (Exception e){
    log.error(e.getMessage(), e);
    throw new JeecgBootException("生成word文档失败，请检查模版和数据是否正确");
}
// after - include the cause so callers can self-diagnose
throw new JeecgBootException("生成word文档失败，请检查模版和数据是否正确: " + e.getMessage(), e);

// pre-flight: ensure every placeholder referenced by the template has a data key
Map<String,Object> data = wordTplGenDTO.getData();
if (data == null) { data = new HashMap<>(); }
mergeSystemVarsToData(data);

try {
    XWPFTemplate.compile(new ByteArrayInputStream(wordTemplateOut.toByteArray())).render(data).write(wordOutputStream);
} catch (Exception e) {
    log.error("poi-tl 渲染失败, data keys={}, cause={}", data.keySet(), e.getMessage(), e);
    throw new JeecgBootException("生成word文档失败，请检查模版和数据是否正确: " + e.getMessage(), e);
}

When it happens

Trigger: The data map is missing a placeholder the template references; a placeholder tag is malformed; poi-tl config/grammar is unsupported; system variables (mergeSystemVarsToData) cannot resolve; the compiled template is structurally invalid.

Common situations: Template defines {{name}} but data has no 'name' key; loop/nested tags misformatted; poi-tl version doesn't support a used policy; the user context (JwtUtil.getUserSystemData) is missing in a background job.

Related errors

• DaoFormat 是 minidao 保留关键字，不允许使用 ，请更改参数定义！
• 下载word模版失败: {message}
• 生成word文档失败: {message}
• 生成Word模版失败: {message}
• 类 {ruleClass} 未实现 IFillRuleHandler 接口

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