jhy/jsoup · error · IllegalArgumentException

The supplied URL, ' ', is malformed. Make sure it is an…

Error message

The supplied URL, '%s', is malformed. Make sure it is an absolute URL, and starts with 'http://' or 'https://'. See https://jsoup.org/cookbook/extracting-data/working-with-urls

What it means

Jsoup's HttpConnection.url(String) wraps java.net.MalformedURLException in an IllegalArgumentException with this message. The library requires an absolute http(s) URL to build its request; relative paths, missing schemes, or unknown protocols cannot be turned into a java.net.URL. This is a fail-fast input validation so the connection is never executed with an unusable URL.

Solutions

1. Prefix the URL with https:// (or http://) so it is absolute
2. Validate the scheme before calling, e.g. url.startsWith("http://")||url.startsWith("https://")
3. Resolve relative URLs against a base: new URL(new URL(baseUrl), relative)
4. Use new URI(url).toURL() in a try/catch to pre-check parseability

Example fix

// before
Document doc = Jsoup.connect("example.com/news").get();
// after
Document doc = Jsoup.connect("https://example.com/news").get();

if (url == null || !(url.startsWith("http://") || url.startsWith("https://"))) throw new IllegalArgumentException("Absolute http(s) URL required: " + url);

boolean isAbsoluteHttpUrl(String u) { try { String p = new URL(u).getProtocol(); return p.equals("http") || p.equals("https"); } catch (MalformedURLException e) { return false; } }

try { Document doc = Jsoup.connect(url).get(); } catch (IllegalArgumentException e) { /* malformed URL: log and skip/fix */ }

When it happens

Trigger: Calling Jsoup.connect("example.com") (no scheme), Jsoup.connect("/relative/path"), Jsoup.connect("ftp://host/file"), or HttpConnection.url(String) with an empty-with-whitespace-but-nonempty string that URL parsing rejects.

Common situations: Hardcoding URLs without the http:// prefix; reading a link from config/user input that is relative; assuming JSoup resolves relative URLs like a browser; typos like 'http:/' or 'htp://'.

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.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Only http & https protocols supported
• You must execute the request before getting a response.
• URL not set. Make sure to call #url(...) before executing…
• Cannot follow redirect with a streamed request body…
• HTTP error fetching URL

AI-assisted analysis of jhy/jsoup@9851ac5d9c (2026-09-08). Data as JSON: /api/errors/81d489239facee2a. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/org/jsoup/helper/HttpConnection.java:154

    /** Create a new Connection that just wraps the provided Request and Response */
    private HttpConnection(Request req, Response res) {
        this.req = req;
        this.res = res;
    }

    @Override
    public Connection url(URL url) {
        req.url(url);
        return this;
    }

    @Override
    public Connection url(String url) {
        Validate.notEmptyParam(url, "url");
        try {
            req.url(new URL(url));
        } catch (MalformedURLException e) {
            throw new IllegalArgumentException(String.format("The supplied URL, '%s', is malformed. Make sure it is an absolute URL, and starts with 'http://' or 'https://'. See https://jsoup.org/cookbook/extracting-data/working-with-urls", url), e);
        }
        return this;
    }

    @Override
    public Connection proxy(@Nullable Proxy proxy) {
        req.proxy(proxy);
        return this;
    }

    @Override
    public Connection proxy(String host, int port) {
        req.proxy(host, port);
        return this;
    }

    @Override
    public Connection userAgent(String userAgent) {

View on GitHub (pinned to 9851ac5d9c)