jeecgboot/JeecgBoot · warning · JeecgBootBizTipException

原始接口路径必须以 / 开头，或填写完整的 http(s) URL

Error message

原始接口路径必须以 / 开头，或填写完整的 http(s) URL

What it means

Thrown when the (twice-decoded) originUrl is neither a full http(s) URL nor a path starting with '/'. The validator requires relative paths to begin with '/' so the reverse proxy/router treats them as application-internal, preventing scheme-relative or bare-segment routing.

Source

Thrown at jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/openapi/controller/OpenApiController.java:266

    private void validOriginUrl(String originUrl) {
        if (oConvertUtils.isEmpty(originUrl)) {
            throw new JeecgBootBizTipException("原始接口路径不能为空");
        }
        String decoded;
        try {
            decoded = java.net.URLDecoder.decode(originUrl, "UTF-8");
            // 二次解码，防止 %252f 这类双重编码绕过
            decoded = java.net.URLDecoder.decode(decoded, "UTF-8");
        } catch (Exception e) {
            throw new JeecgBootBizTipException("原始接口路径包含非法字符");
        }
        //update-begin---author:scott ---date:20260429  for：【issues/9590】微服务nginx部署openApi接口访问不到-----------
        // 微服务部署时，OpenAPI 配置的接口可能位于其他微服务模块（如 erp 7003），允许 originUrl 直接配置完整 http(s) URL
        String lower = decoded.toLowerCase();
        boolean isFullHttpUrl = lower.startsWith("http://") || lower.startsWith("https://");
        if (!isFullHttpUrl) {
            if (!decoded.startsWith("/")) {
                throw new JeecgBootBizTipException("原始接口路径必须以 / 开头，或填写完整的 http(s) URL");
            }
            if (decoded.startsWith("//") || decoded.startsWith("/\\")) {
                throw new JeecgBootBizTipException("原始接口路径不能以 // 或 /\\ 开头");
            }
            if (lower.contains("://") || lower.startsWith("file:") || lower.startsWith("ftp:") || lower.startsWith("gopher:")
                    || lower.startsWith("jar:") || lower.startsWith("netdoc:")) {
                throw new JeecgBootBizTipException("原始接口路径仅支持相对路径或 http(s) 完整URL");
            }
        } else {
            // 即便是完整URL，也禁止其它危险协议（防止 http://x@file:/... 之类的绕过场景）
            String afterScheme = lower.substring(lower.indexOf("://") + 3);
            if (afterScheme.contains("file:") || afterScheme.contains("ftp:") || afterScheme.contains("gopher:")
                    || afterScheme.contains("jar:") || afterScheme.contains("netdoc:")) {
                throw new JeecgBootBizTipException("原始接口路径不允许嵌套 file/ftp/gopher/jar/netdoc 等协议");
            }
        }
        if (decoded.contains("..")) {
            throw new JeecgBootBizTipException("原始接口路径不能包含 ..");

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Prefix the origin_url with '/', e.g. '/sys/user/list'.
2. If the target lives on another microservice, supply the full 'http://' or 'https://' URL instead.
3. Check the admin form for client-side trimming that removes leading slashes.

Example fix

// before: originUrl = "jeecgdemo/test/list"
// after:  originUrl = "/jeecgdemo/test/list"

// Ensure the value is either a full http(s) URL or starts with a single '/'
private static boolean isValidOriginShape(String s) {
    if (s == null) return false;
    String l = s.toLowerCase();
    if (l.startsWith("http://") || l.startsWith("https://")) return true;
    return s.startsWith("/") && !s.startsWith("//") && !s.startsWith("/\\");
}

When it happens

Trigger: Configuring an OpenAPI origin_url as 'sys/user/list' (missing leading slash), or 'http:\\x' which after decoding no longer matches the http:// prefix check.

Common situations: Operators copy an endpoint path from controller code but drop the leading slash; frontend forms that strip a leading '/' during trimming; switching from full URL back to relative path without re-adding '/'.

Related errors

• 原始接口路径包含非法字符
• 原始接口路径仅支持相对路径或 http(s) 完整URL
• 原始接口路径不能以 // 或 /\ 开头
• 原始接口路径不允许嵌套 file/ftp/gopher/jar/netdoc 等协议
• 原始接口路径不能包含 ..

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