iflytek/astron-agent · error · BusinessException

MODEL_URL_ILLEGAL_FAILED

MODEL_URL_ILLEGAL_FAILED

Error message

MODEL_URL_ILLEGAL_FAILED

What it means

validateUrlParam rejects a model API URL whose protocol is not in the configured allowlist (props.getAllowedSchemes(), typically http/https). It throws MODEL_URL_ILLEGAL_FAILED as a BusinessException before any network request is made, as part of SSRF protection.

Solutions

1. Check the model URL passed to buildModelApiUrlNew/validateSsrfForNodes starts with an allowed scheme (usually https:// or http://).
2. Add the required scheme to props.getAllowedSchemes() in the SSRF guard configuration if the scheme is legitimately needed.
3. Inspect SsrfValidators.normalizeFlex output to see the effectiveUrl actually being validated (redirect-style normalization can change the scheme).

Example fix

// before
String url = "ftp://models.example.com/api";
// after
String url = "https://models.example.com/api";

final String url = modelEndpoint;
java.net.URI uri = java.net.URI.create(url);
if (!"https".equals(uri.getScheme()) && !"http".equals(uri.getScheme())) {
    throw new IllegalArgumentException("Model URL must be http(s): " + url);
}

try {
    ssrfParamGuard.validateUrlParam(url);
} catch (BusinessException e) {
    if (ResponseEnum.MODEL_URL_ILLEGAL_FAILED.equals(e.getCode())) {
        log.warn("Rejected model URL scheme: {}", sanitize(url));
    }
    throw e;
}

When it happens

Trigger: buildModelApiUrlNew or validateSsrfForNodes is called with a model base URL whose scheme is not in props.getAllowedSchemes(), e.g. 'ftp://host/model' or 'file:///etc/passwd'. Note the identical guard is duplicated: the first throw wins, so this specific code fires before the RESPONSE_FAILED variant.

Common situations: Misconfigured model endpoint in the console (missing 'https://' prefix, or a custom scheme), YAML/env config where allowed-schemes omits a needed scheme, or a URL that after normalizeFlex resolves to a different scheme.

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

• Skill resource URL is not allowed
• MODEL_URL_CHECK_FAILED
• MODEL_URL_CHECK_FAILED
• TOOLBOX_URL_HTTP_HTTPS_ONLY
• RESPONSE_FAILED

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

Appendix: source

Thrown at console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/util/ssrf/SsrfParamGuard.java:57

     * Validation steps:
     * </p>
     * <ul>
     * <li>Check if the URL scheme (protocol) is allowed.</li>
     * <li>Check if the host is blocked by the configured IP blacklist (supporting both hostnames and
     * IPs).</li>
     * </ul>
     *
     * @param url the URL string to validate
     * @throws BusinessException if the URL does not pass validation
     */
    public void validateUrlParam(String url) {
        try {
            SsrfValidators.Normalized n = SsrfValidators.normalizeFlex(url);
            URL u = n.effectiveUrl;

            // 1) Protocol and port
            if (!SsrfValidators.isAllowedScheme(u.getProtocol(), props.getAllowedSchemes())) {
                throw new BusinessException(ResponseEnum.MODEL_URL_ILLEGAL_FAILED);
            }
            if (!SsrfValidators.isAllowedScheme(u.getProtocol(), props.getAllowedSchemes())) {
                throw new BusinessException(
                        ResponseEnum.RESPONSE_FAILED,
                        "Only allowed schemes: " + props.getAllowedSchemes());
            }

            // 2) IP blacklist (compatible with hostnames and IPs)
            List<String> ipBlacklist = props.getIpBlaklist();
            if (SsrfValidators.isHostDeniedByIpPolicy(
                    u.getHost(), ipBlacklist, props.getIpWhitelist(), Dns.SYSTEM)) {
                throw new BusinessException(ResponseEnum.MODEL_URL_CHECK_FAILED);
            }

        } catch (BusinessException e) {
            throw e;
        } catch (Exception e) {
            log.error("[SSRF] URL validation failed", e);

View on GitHub (pinned to 5e758547a8)