apache/shenyu · error · IllegalArgumentException

Invalid URL format

Error message

Invalid URL format

What it means

validateUrlForSSRF parses the URL with OkHttp's HttpUrl.parse; if parsing fails (the string is not a well-formed absolute HTTP URL) it throws IllegalArgumentException "Invalid URL format". This prevents malformed strings from ever reaching request execution.

Solutions

1. Enter the URL with an explicit scheme: http:// or https:// plus valid host and path.
2. Trim whitespace and remove quotes/placeholders from the configured value.
3. Pre-validate in the UI with a URL parser before saving the config.
4. Catch IllegalArgumentException and show which field contains the malformed URL.

Example fix

// before
validateUrlForSSRF("backend.example.com:8080/api");
// after
validateUrlForSSRF("http://backend.example.com:8080/api");

HttpUrl parsed = HttpUrl.parse(url);
if (parsed == null) {
    throw new IllegalArgumentException("Not a valid absolute http(s) URL: " + url);
}
if (!url.trim().equals(url)) throw new IllegalArgumentException("URL has surrounding whitespace");

boolean isParsableUrl(String s) { return s != null && HttpUrl.parse(s.trim()) != null; }

try {
    UrlSecurityUtils.validateUrlForSSRF(url);
} catch (IllegalArgumentException e) {
    return ResponseEntity.badRequest().body("Invalid URL: use a full http(s):// URL");
}

When it happens

Trigger: Passing strings without a scheme ('example.com/api'), with unsupported schemes relative to OkHttp's parser, containing invalid characters/spaces, or garbage/placeholder values ('${HOST}', 'localhost:99999').

Common situations: Users entering host names without http(s):// in admin forms; config values with unresolved env placeholders; trailing whitespace or hidden characters pasted from docs.

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

• URL cannot be empty
• Only HTTP and HTTPS protocols are allowed
• Host cannot be empty
• Access to localhost is not allowed
• Access to private or internal IP addresses is not allowed

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/953925551437db79. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-admin/src/main/java/org/apache/shenyu/admin/utils/UrlSecurityUtils.java:57

     * Private constructor to prevent instantiation.
     */
    private UrlSecurityUtils() {
    }

    /**
     * Validate URL to prevent SSRF attacks.
     *
     * @param url the URL to validate
     * @throws IllegalArgumentException if the URL is not safe for external requests
     */
    public static void validateUrlForSSRF(final String url) {
        if (Objects.isNull(url) || url.trim().isEmpty()) {
            throw new IllegalArgumentException("URL cannot be empty");
        }

        HttpUrl parsedUrl = HttpUrl.parse(url);
        if (Objects.isNull(parsedUrl)) {
            throw new IllegalArgumentException("Invalid URL format");
        }

        String protocol = parsedUrl.scheme();

        // Only allow HTTP and HTTPS protocols
        if (!HTTP_PROTOCOL.equals(protocol) && !HTTPS_PROTOCOL.equals(protocol)) {
            throw new IllegalArgumentException("Only HTTP and HTTPS protocols are allowed");
        }

        // Validate host for SSRF protection using the same URL parser as request execution.
        validateHostForSSRF(parsedUrl.host(), parsedUrl.port());
    }

    /**
     * Validate host to prevent SSRF attacks.
     *
     * @param host the host to validate
     * @param port the port to validate

View on GitHub (pinned to 567142e072)