jeecgboot/JeecgBoot · critical · IllegalArgumentException

Path参数包含非法字符:

Error message

Path参数包含非法字符: 

What it means

Thrown by PluginToolBuilder.buildUrl() when a Path-type URL parameter contains path traversal or path separator characters: '..', '/', '\', '%2e', or '%2f' (case-insensitive). This prevents path traversal injection when building REST API URLs from OpenAPI/plugin parameter definitions (issue #9421).

Source

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

                JSONObject param = parameters.getJSONObject(i);
                if (param == null) {
                    continue;
                }
                String paramName = param.getString("name");
                String paramLocation = param.getString("location");

                if (!"Path".equalsIgnoreCase(paramLocation)) {
                    continue;
                }

                Object value = args.get(paramName);
                if (value != null) {
                    //update-begin---author:wangshuai---date:2026-03-30---for:【issues/9421】buildUrl路径遍历漏洞修复---
                    String paramValue = value.toString();
                    // 防止路径遍历注入：拒绝包含 ..、/ 、\ 的路径参数
                    if (paramValue.contains("..") || paramValue.contains("/") || paramValue.contains("\\")
                            || paramValue.toLowerCase().contains("%2e") || paramValue.toLowerCase().contains("%2f")) {
                        throw new IllegalArgumentException("Path参数包含非法字符: " + paramName);
                    }
                    url = url.replace("{" + paramName + "}", paramValue);
                    //update-end---author:wangshuai---date:2026-03-30---for:【issues/9421】buildUrl路径遍历漏洞修复---
                }
            }
        }

        return url;
    }

    /**
     * 构建请求头
     */
    private static HttpHeaders buildHttpHeaders(JSONArray parameters, JSONObject args, Map<String, String> defaultHeaders) {
        HttpHeaders httpHeaders = new HttpHeaders();

        // 添加默认请求头
        if (defaultHeaders != null) {

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Ensure Path parameter values are simple identifiers (UUIDs, numeric IDs) without slashes or dots.
2. If the parameter legitimately needs sub-paths, restructure the API spec to use separate path segments or query parameters.
3. Validate LLM-generated tool call arguments before invoking the plugin.

// Validate Path parameters before calling buildUrl
for (Map.Entry<String, Object> entry : args.entrySet()) {
    String val = entry.getValue() == null ? "" : entry.getValue().toString();
    if (val.contains("..") || val.contains("/") || val.contains("\\")
            || val.toLowerCase().contains("%2e") || val.toLowerCase().contains("%2f")) {
        throw new IllegalArgumentException("参数" + entry.getKey() + "包含非法字符");
    }
}

private static boolean isSafePathParam(String value) {
    if (value == null) return true;
    String lower = value.toLowerCase();
    return !value.contains("..") && !value.contains("/") && !value.contains("\\")
        && !lower.contains("%2e") && !lower.contains("%2f");
}

try {
    String url = buildUrl(baseUrl, path, parameters, args);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Path参数包含非法字符")) {
        log.warn("Plugin path parameter rejected: {}", e.getMessage());
        throw new JeecgBootException("插件参数包含非法路径字符");
    }
    throw e;
}

When it happens

Trigger: An AI agent calls a plugin/tool whose OpenAPI spec defines a Path parameter, and the argument value contains '..', '/', '\', or URL-encoded equivalents. For example: a plugin with path '/api/files/{id}' receives id='../../etc/passwd' or id='foo/bar'.

Common situations: An LLM-generated function call includes a path-traversal payload in a Path parameter; a plugin is misconfigured to accept free-form path segments; URL-encoded traversal attempts (%2e%2e%2f) are passed.

Related errors

• 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/8fb3955752339494. Report an issue: GitHub.