jeecgboot/JeecgBoot · critical · JeecgBootException

文件路径包含非法字符

Error message

文件路径包含非法字符

What it means

Thrown by EmbeddingHandler.ensureFile() when a resolved file path escapes the upload directory after normalization. The method first calls SsrfFileTypeFilter.checkPathTraversal() to reject '..' and '%2e' patterns, then resolves the relative path against the upload root and checks that the normalized result still starts with the upload root. This is a path traversal / directory traversal security guard (issues #9424, #9425).

Source

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

            }
            fileName = FilenameUtils.getName(fileName);
            tempFilePath = tempFilePath + fileName;
            FileDownloadUtils.download2DiskFromNet(filePath, tempFilePath);
            filePath = tempFilePath;
        } else {
            //update-begin---author:wangshuai---date:2026-03-30---for:【issues/9424】CommandExecUtil 命令执行过程中存在疑似路径遍历漏洞/【issues/9425】EmbeddingHandler 知识库解析过程中疑似存在路径遍历漏洞---
            // 1. 路径遍历检查：拒绝 .. 和 %2e 等绕过手段
            SsrfFileTypeFilter.checkPathTraversal(filePath);
            // 2. 标准化路径并校验是否在 uploadpath 范围内
            Path root = Paths.get(uploadpath).toAbsolutePath().normalize();
            //update-begin---author:wangshuai ---date:2026-04-13  for：zip文件 filePath 以 \ 或 / 开头，在Windows下被Path.resolve当成驱动器根路径导致误判路径遍历，先剥掉前导分隔符-----------
            // 去除前导分隔符，保证作为相对路径 resolve 到 uploadpath 之下
            String relativePath = filePath.replaceAll("^[\\\\/]+", "");
            Path target = root.resolve(relativePath).toAbsolutePath().normalize();
            //update-end---author:wangshuai ---date:2026-04-13  for：zip文件 filePath 以 \ 或 / 开头，在Windows下被Path.resolve当成驱动器根路径导致误判路径遍历，先剥掉前导分隔符-----------
            if (!target.startsWith(root)) {
                log.error("检测到路径遍历攻击! filePath: {}, 解析后: {}", filePath, target);
                throw new JeecgBootException("文件路径包含非法字符");
            }
            filePath = target.toString();
            //update-end---author:wangshuai---date:2026-03-30---for:【issues/9424】CommandExecUtil 命令执行过程中存在疑似路径遍历漏洞/【issues/9425】EmbeddingHandler 知识库解析过程中疑似存在路径遍历漏洞---
        }
        return filePath;
    }


}

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Ensure the filePath in document metadata is always a relative path under the upload directory.
2. Do not allow user-controllable input to set the filePath metadata field directly.
3. If the error persists with legitimate files, check that uploadpath is correctly configured and the file actually resides beneath it.

// Ensure filePath is relative and within upload directory before processing
String relativePath = filePath.replaceAll("^[\\\\/]+", "");
Path root = Paths.get(uploadpath).toAbsolutePath().normalize();
Path target = root.resolve(relativePath).toAbsolutePath().normalize();
if (!target.startsWith(root)) {
    throw new JeecgBootException("文件路径非法");
}

try {
    filePath = ensureFile(filePath);
} catch (JeecgBootException e) {
    if (e.getMessage().contains("文件路径包含非法字符")) {
        log.error("Path traversal attempt detected for filePath");
        throw new JeecgBootException("文件路径不合法，请检查文件配置");
    }
    throw e;
}

When it happens

Trigger: A filePath containing '../' sequences (after any leading separators are stripped) that, when resolved against the upload root, points outside the upload directory. Also triggered by crafted paths using URL encoding or OS-specific separators that bypass the initial checkPathTraversal but resolve outside root.

Common situations: Malicious or corrupted filePath in document metadata pointing to system files; a zip extraction entry with a relative path that escaped the target dir and was stored as the filePath; a testing/debugging scenario with an absolute path from another drive or root.

Related errors

• ZIP 路径穿越攻击被阻止:{entryName}
• Illegal access to path outside of base directory.
• 非法业务路径，禁止访问上传目录之外的路径: ${bizPath}
• 非法存储路径，路径包含遍历字符: {storePath}
• 存储路径校验失败: {storePath}

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