jeecgboot/JeecgBoot · error · JeecgBootException

文件名包含非法字符，无法处理该文件

Error message

文件名包含非法字符，无法处理该文件

What it means

Thrown by EmbeddingHandler.parseFileByMinerU() when CommandExecUtil.validateFilePath() detects dangerous characters in either the file's absolute path or its name. The IllegalArgumentException from validateFilePath is caught and re-thrown as a user-facing JeecgBootException. This is a security guard preventing command injection through filenames passed to the external magic-pdf command.

Source

Thrown at jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag/src/main/java/org/jeecg/modules/airag/llm/handler/EmbeddingHandler.java:905

        String filePath = metadataJson.getString(LLMConsts.KNOWLEDGE_DOC_METADATA_FILEPATH);
        AssertUtils.assertNotEmpty("请先上传文件", filePath);
        filePath = ensureFile(filePath);

        File docFile = new File(filePath);
        String fileType = FilenameUtils.getExtension(filePath);
        if (!docFile.exists()
                || "txt".equalsIgnoreCase(fileType)
                || "md".equalsIgnoreCase(fileType)) {
            return ;
        }

        // 安全校验：拒绝文件名/路径中含有 Shell 注入字符的文件，防止命令注入
        try {
            CommandExecUtil.validateFilePath(docFile.getAbsolutePath());
            CommandExecUtil.validateFilePath(docFile.getName());
        } catch (IllegalArgumentException e) {
            log.error("文件路径包含非法字符，拒绝执行 MinerU 解析: {}", e.getMessage());
            throw new JeecgBootException("文件名包含非法字符，无法处理该文件");
        }

        // 使用 String[] 数组构建命令，避免 split(" ") 带来的参数边界问题
        String[] command;
        if (oConvertUtils.isNotEmpty(knowConfigBean.getCondaEnv())) {
            command = new String[]{"conda", "run", "-n", knowConfigBean.getCondaEnv(), "magic-pdf"};
        } else {
            command = new String[]{"magic-pdf"};
        }

        String outputPath = docFile.getParentFile().getAbsolutePath();
        String[] args = {
                "-p", docFile.getAbsolutePath(),
                "-o", outputPath,
        };

        try {
            String execLog = CommandExecUtil.execCommand(command, args);

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Rename the source file to remove special characters (& | ; < > ` $ ! " ' and newlines) before uploading.
2. Sanitize filenames at upload time in CommonUtils.uploadLocal to strip or replace dangerous characters.
3. If the upload directory path contains restricted characters, relocate the upload directory.

// Sanitize filename before it reaches MinerU processing
String safeName = docFile.getName().replaceAll("[&|;<>`$!\"'\r\n]", "_");
File safeFile = new File(docFile.getParentFile(), safeName);
// verify before calling parseFileByMinerU
CommandExecUtil.validateFilePath(safeFile.getAbsolutePath());
CommandExecUtil.validateFilePath(safeFile.getName());

private static boolean isMinerUSafeFilename(String name) {
    return name != null && !Pattern.compile("[&|;<>`$!\"'\r\n]").matcher(name).find();
}

try {
    parseFileByMinerU(doc);
} catch (JeecgBootException e) {
    if (e.getMessage().contains("文件名包含非法字符")) {
        log.warn("File rejected by MinerU safety check: {}", doc.getId());
        throw new JeecgBootException("文件名含特殊字符，请重命名后重新上传");
    }
    throw e;
}

When it happens

Trigger: A knowledge-base document file whose absolute path or filename contains any of: & | ; < > ` $ ! " ' \r \n. The file passes earlier checks but fails the injection guard before being passed as an argument to the conda/magic-pdf command.

Common situations: User uploaded a file with special characters in the original filename that were preserved through the upload pipeline; the upload directory path itself contains a restricted character; a downloaded web resource filename includes quotes or semicolons.

Related errors

• 命令参数包含非法字符，已拒绝执行:
• 文件路径包含非法字符，已拒绝处理:
• 文件路径包含非法字符
• 解压文件数量超限，可能是zip bomb攻击
• 解压总大小超限，可能是zip bomb攻击

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