jeecgboot/JeecgBoot · error · RuntimeException

添加图片异常: {message}

Error message

添加图片异常: {message}

What it means

WordUtil.addImage() inserts an image (web-downloaded or local) into an XWPFParagraph via POI. The outer try wraps ANY exception (fetch failure, POI addPicture error, missing width/height) as a RuntimeException with the cause message; a finally block closes the input stream.

Source

Thrown at jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag/src/main/java/org/jeecg/modules/airag/wordtpl/utils/WordUtil.java:803

                    case "center":
                        paragraph.setAlignment(ParagraphAlignment.CENTER);
                        break;
                    case "right":
                        paragraph.setAlignment(ParagraphAlignment.RIGHT);
                        break;
                    case "alignment":
                        paragraph.setAlignment(ParagraphAlignment.BOTH);
                        break;
                    default:
                        paragraph.setAlignment(ParagraphAlignment.LEFT);
                        break;
                }
            } else {
                paragraph.setAlignment(ParagraphAlignment.LEFT);
            }
        } catch (Exception e) {
            log.error("添加图片异常", e);
            throw new RuntimeException("添加图片异常: " + e.getMessage(), e);
        } finally {
            if (null != in) {
                try {
                    in.close();
                } catch (Exception e) {
                    // ignore
                    log.error("关闭图片流异常", e);
                }
            }
        }
    }

    /**
     * 添加图片
     *
     * @param imageData 图片流
     * @param doc   文档对象
     * @param run   文档运行对象

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Read the cause message in '添加图片异常'.
2. Verify the image URL resolves and passes SSRF checks, or the local path is inside the upload dir.
3. Ensure width and height are present and positive in the content JSON.
4. Confirm the byte stream matches the picture type POI expects.

// validate image content JSON before insertion
String value = content.getString("value");
if (oConvertUtils.isEmpty(value)) { throw new IllegalArgumentException("图片地址为空"); }
if (!content.containsKey("width") || !content.containsKey("height")) {
    throw new IllegalArgumentException("缺少 width/height");
}

try { WordUtil.addImage(paragraph, content); }
catch (RuntimeException e) {
    log.error("插入图片失败, value={}", content.getString("value"), e);
    // continue rendering without the image rather than failing the whole doc
}

When it happens

Trigger: Remote image 404/timeout; SsrfFileTypeFilter rejects the URL (loopback/link-local); local path rejected by the traversal guard (error 129); width/height fields missing or non-numeric; unsupported picture format for addPicture.

Common situations: Broken/expired image URL; missing width/height in the content JSON; non-PNG/JPEG bytes passed as PNG; permission reading the local file.

Related errors

• 生成Word模版失败: {message}
• 下载word模版失败: {message}
• 解析word模版失败: {message}
• 生成word文档失败: {message}
• 非法文件路径，禁止访问上传目录之外的文件: {imageUrl}

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