iflytek/astron-agent · warning · BusinessException

TOOLBOX_IP_IN_BLACKLIST

TOOLBOX_IP_IN_BLACKLIST

Error message

TOOLBOX_IP_IN_BLACKLIST

What it means

TOOLBOX_IP_IN_BLACKLIST is thrown when a resolved IP of the URL's host exactly matches an entry in the configured IP blacklist (IP_BLACK_LIST category from the ConfigInfo table). Comparison is exact string equality on the resolved address after trimming blacklist entries.

Solutions

1. Check the IP_BLACK_LIST configuration (ConfigInfo table) and confirm whether the resolved IP should really be denied.
2. If the block is wrong/outdated, update the blacklist to remove or correct the entry.
3. Resolve the target domain and compare with the blacklist; switch to a host not resolving to a blacklisted IP.
4. For domain-based access, prefer whitelisting the domain (DOMAIN_WHITE_LIST) so IP changes don't break it — but note the built-in restricted-address policy still applies.

Example fix

// before: target resolves to 203.0.113.7 which is in IP_BLACK_LIST
urlCheckTool.checkUrl("http://blocked-target.example/"); // TOOLBOX_IP_IN_BLACKLIST
// after: admin fixes the stale blacklist entry in ConfigInfo (IP_BLACK_LIST)
// value: "203.0.113.7,198.51.100.9" -> "198.51.100.9"
urlCheckTool.checkUrl("http://blocked-target.example/"); // passes

static boolean ipBlacklisted(String url, java.util.List<String> ipBlackList) {
    try {
        String host = new URI(url).getHost();
        if (host == null) return false;
        for (InetAddress a : InetAddress.getAllByName(host)) {
            String ip = a.getHostAddress();
            if (ipBlackList.stream().map(String::trim).anyMatch(ip::equals)) return true;
        }
        return false;
    } catch (Exception e) { return false; }
}

null

try {
    urlCheckTool.checkUrl(url);
} catch (BusinessException e) {
    if ("TOOLBOX_IP_IN_BLACKLIST".equals(e.getCode())) {
        // inform user the destination IP is deny-listed; escalate to admin if legitimate
    } else { throw e; }
}

When it happens

Trigger: Calling checkUrl/checkBlackList where any address returned by InetAddress.getAllByName(host) equals (as a string) one of the comma-separated entries in the IP_BLACK_LIST config row.

Common situations: The target domain's IP was added to the deny list by an administrator, the domain recently moved to a blacklisted IP (hosting provider blocklist), or an overly broad blacklist entry that also covers the legitimate target's current address.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• TOOLBOX_URL_SHORT_NOT_SUPPORTED
• Only HTTP and HTTPS remote resources are allowed
• Remote resource URL must not include user information
• Outbound address is blocked
• Outbound address is not globally routable

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/259e2123b80a82d4. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/tool/UrlCheckTool.java:194

            throw new BusinessException(ResponseEnum.TOOLBOX_URL_ILLEGAL);
        }
        for (InetAddress inet : addresses) {
            if (SsrfValidators.isIpLiteral(asciiHost)
                    && SsrfValidators.isAddressMatchedByIpRules(inet, ipWhiteList)) {
                log.debug("URL destination allowed by IP whitelist, host={}, ip={}", asciiHost, inet.getHostAddress());
                continue;
            }
            if (SsrfValidators.isRestrictedAddress(inet)) {
                throw new BusinessException(ResponseEnum.TOOLBOX_URL_ILLEGAL);
            }
            if (domainWhitelisted) {
                continue;
            }
            String ip = inet.getHostAddress();

            // IPv4 blacklist
            if (ipBlackList.stream().map(String::trim).anyMatch(ip::equals)) {
                throw new BusinessException(ResponseEnum.TOOLBOX_IP_IN_BLACKLIST);
            }

            // Network segment blacklist (only effective for IPv4; IPv6 can be extended)
            if (inet instanceof Inet4Address) {
                for (String segment : segmentBlackList) {
                    if (isIpInRange(ip, segment)) {
                        throw new BusinessException(ResponseEnum.TOOLBOX_IP_IN_BLACKLIST);
                    }
                }
            }
        }
    }

    /**
     * Determines if IPv4 falls within CIDR range (like 10.0.0.0/8). Returns false directly for invalid
     * segments or IPv6 scenarios.
     *
     * @param ip the IP address to check

View on GitHub (pinned to 5e758547a8)