jeecgboot/JeecgBoot · error · JeecgBootException

非法URL：主机名无法解析

Error message

非法URL：主机名无法解析

What it means

Thrown by checkSsrfHttpUrl when InetAddress.getAllByName(host) throws UnknownHostException — the hostname cannot be resolved via DNS. This is a network-level failure: either the domain does not exist, DNS is unreachable, or the hostname has a typo. The method wraps the original UnknownHostException into a JeecgBootException with a clear message.

Source

Thrown at jeecg-boot/jeecg-boot-base-core/src/main/java/org/jeecg/common/util/filter/SsrfFileTypeFilter.java:351

        if (scheme == null || !(scheme.equalsIgnoreCase("http") || scheme.equalsIgnoreCase("https"))) {
            throw new JeecgBootException("非法URL：仅允许 http / https 协议");
        }
        String host = uri.getHost();
        if (StringUtils.isBlank(host)) {
            throw new JeecgBootException("非法URL：主机名为空");
        }
        // 去掉 IPv6 的中括号
        if (host.startsWith("[") && host.endsWith("]")) {
            host = host.substring(1, host.length() - 1);
        }
        try {
            for (InetAddress addr : InetAddress.getAllByName(host)) {
                if (addr.isLoopbackAddress() || addr.isLinkLocalAddress()) {
                    throw new JeecgBootException("非法URL：禁止访问本机或链路本地地址 " + addr.getHostAddress());
                }
            }
        } catch (UnknownHostException e) {
            throw new JeecgBootException("非法URL：主机名无法解析");
        }
    }
    //update-end---author:zhangdaihao ---date:2026-04-15  for：【issues/9553】修复二次SSRF漏洞，对HTTP下载URL进行安全校验-----------

    /**
     * 批量校验文件路径安全性（逗号分隔的多个文件路径）
     * @param files 逗号分隔的文件路径
     */
    public static void checkPathTraversalBatch(String files) {
        if (StringUtils.isBlank(files)) {
            return;
        }
        for (String file : files.split(",")) {
            if (StringUtils.isNotBlank(file)) {
                checkPathTraversal(file.trim());
            }
        }
    }

View on GitHub (pinned to 96fb33f5ec)

Solutions

  1. Verify the hostname is correct and resolvable from the application server (test with 'nslookup' or 'dig' on the server).
  2. If using internal hostnames, ensure DNS or /etc/hosts is configured on the application server.
  3. Check network policies/firewall rules that may block DNS (port 53).
  4. In containerized deployments, verify Docker/Kubernetes DNS service is running and the hostname matches the service discovery name.

Example fix

// No code fix — verify DNS resolution from the server host.
// Debug command:
//   nslookup <hostname-from-error>
// If DNS is unavailable, add a static hosts entry:
//   echo "10.0.0.5 minio.internal" >> /etc/hosts
Defensive patterns

Strategy: try-catch

Validate before calling

try {
    InetAddress.getAllByName(hostFromUrl);
} catch (UnknownHostException e) {
    return Result.error("主机名无法解析，请检查网络或DNS配置: " + hostFromUrl);
}

Try / catch

try {
    SsrfFileTypeFilter.checkSsrfHttpUrl(fileUrl);
} catch (JeecgBootException e) {
    if (e.getMessage().contains("无法解析")) {
        log.warn("DNS resolution failed for URL host: {}", fileUrl);
    }
    return Result.error(e.getMessage());
}

Prevention

When it happens

Trigger: Hostname has a typo (e.g., 'exmaple.com'), domain does not exist, DNS server is down, the server has no network access, or the hostname is a non-routable internal name not registered in DNS.

Common situations: Air-gapped or restricted network environment where external DNS is blocked; typo in a configured MinIO/OSS endpoint; service DNS name changed after migration; containerized environment missing DNS configuration.

Related errors

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