iflytek/astron-agent · error · BusinessException

TOOLBOX_URL_ILLEGAL

TOOLBOX_URL_ILLEGAL

Error message

TOOLBOX_URL_ILLEGAL

What it means

In UrlCheckTool.checkUrlForIPv6, TOOLBOX_URL_ILLEGAL is thrown when java.net.URI cannot extract a host from the URL (uri.getHost() == null). This happens for URLs with no authority component, malformed authority, or schemes URI cannot parse, meaning the URL is not a well-formed http(s) address.

Solutions

1. Validate the URL on the client/entry point and require a full http(s) URL with a host before submitting.
2. Percent-encode spaces and special characters in the URL.
3. Check the input string for truncation or missing host and re-enter the complete URL.
4. Wrap calls in a pre-check that constructs new URI(url) and requires getHost() != null.

Example fix

// before
String url = "http://"; // no host
urlCheckTool.checkUrl(url); // TOOLBOX_URL_ILLEGAL
// after
URI uri = new URI("http://example.com/path");
if (uri.getHost() != null) {
    urlCheckTool.checkUrl("http://example.com/path");
}

static boolean hasParsableHost(String url) {
    try {
        return new URI(url).getHost() != null;
    } catch (URISyntaxException e) {
        return false;
    }
}
// call only if hasParsableHost(url)

null

try {
    urlCheckTool.checkUrl(url);
} catch (BusinessException e) {
    if ("TOOLBOX_URL_ILLEGAL".equals(e.getCode())) {
        // show "URL is malformed or not allowed" validation error
    } else { throw e; }
}

When it happens

Trigger: Calling checkUrl / checkUrlForIPv6 with a URL like "http://", a URL with no authority (e.g. "file:/path"), a malformed authority (e.g. "http://exa mple.com"), or any string that parses as a URI but yields no host.

Common situations: Users pasting truncated URLs into the toolbox, URLs containing spaces or unencoded special characters, empty host after protocol, or client-side transformations that strip the authority.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Only HTTP and HTTPS remote resources are allowed
• Remote resource URL must not include user information
• User UID cannot be null
• DUPLICATE_BOT_NAME
• PARAMETER_ERROR

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

Appendix: source

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

    // Common short link domains
    private static final Set<String> SHORT_LINK_DOMAINS = Set.of(
            "bit.ly", "tinyurl.com", "t.co", "rebrandly.com", "is.gd", "t.ly",
            "monojson.com", "t.cn", "url.cn", "dwz.cn");

    /**
     * Throws exception if URL host is IPv6 (current policy: disable IPv6). Silently returns on parsing
     * exception (doesn't affect main flow).
     *
     * @param url the URL to check for IPv6
     * @throws BusinessException if the URL host is IPv6 or malformed
     */
    public static void checkUrlForIPv6(String url) {
        try {
            URI uri = new URI(url);
            String host = uri.getHost();
            if (host == null) {
                throw new BusinessException(ResponseEnum.TOOLBOX_URL_ILLEGAL);
            }
            InetAddress inet = InetAddress.getByName(host);
            if (inet instanceof Inet6Address) {
                log.info("URL host is IPv6: {}", host);
                throw new BusinessException(ResponseEnum.TOOLBOX_URL_ILLEGAL);
            }
        } catch (BusinessException e) {
            throw e;
        } catch (Exception ignore) {
            // Parsing failure not handled here, let upper layer handle uniformly
        }
    }

    /**
     * Rejects IPv4-mapped IPv6 address format, such as: http://[::ffff:192.168.1.1]/path
     *
     * @param url the URL to check for IPv4-mapped IPv6 format
     * @throws BusinessException if the URL contains IPv4-mapped IPv6 format

View on GitHub (pinned to 5e758547a8)