jhy/jsoup · error · IllegalArgumentException

URL not set. Make sure to call #url(...) before executing…

Error message

URL not set. Make sure to call #url(...) before executing the request.

What it means

The request's url() getter throws when the URL was never set: internally the URL field is a sentinel UnsetUrl until url(URL) is called. This surfaces when execute() or any code path asks a RequestBase for its URL before one was configured. It enforces that every request targets an address.

Solutions

1. Call url(URL) or url(String) with an absolute http(s) URL before executing
2. Add an assertion/validation that the URL field is populated before execute()
3. Use Jsoup.connect(url) which sets the URL up front

Example fix

// before
Connection conn = Jsoup.newRequest();
conn.method(Connection.Method.POST);
Connection.Response res = conn.execute();
// after
Connection conn = Jsoup.newRequest();
conn.url("https://example.com/api");
conn.method(Connection.Method.POST);
Connection.Response res = conn.execute();

Objects.requireNonNull(requestUrl, "Request URL must be set before execute()");

try { Connection.Response res = conn.execute(); } catch (IllegalArgumentException e) { /* URL was never set: configure and retry */ }

When it happens

Trigger: Building a Request/Connection via newRequest() or the Request constructor and calling execute() (or url()) without ever calling url(...); copying a request object that lacked a URL.

Common situations: Programmatic request construction (Connection.newRequest()) where url() is set conditionally; test harnesses that forget configuration; code paths that set method/headers/cookies but skip the URL.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• You must execute the request before getting a response.
• Cannot follow redirect with a streamed request body…
• HTTP error fetching URL
• Unhandled content type. Must be a text or XML media type
• Too many redirects occurred trying to load URL

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

Appendix: source

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

        private Base() {
            headers = new LinkedHashMap<>();
            cookies = new LinkedHashMap<>();
        }

        private Base(Base<T> copy) {
            url = copy.url; // unmodifiable object
            method = copy.method;
            headers = new LinkedHashMap<>();
            for (Map.Entry<String, List<String>> entry : copy.headers.entrySet()) {
                headers.put(entry.getKey(), new ArrayList<>(entry.getValue()));
            }
            cookies = new LinkedHashMap<>(); cookies.putAll(copy.cookies); // just holds strings
        }

        @Override
        public URL url() {
            if (url == UnsetUrl)
                throw new IllegalArgumentException("URL not set. Make sure to call #url(...) before executing the request.");
            return url;
        }

        @Override
        public T url(URL url) {
            Validate.notNullParam(url, "url");
            this.url = new UrlBuilder(url).build();
            return (T) this;
        }

        @Override
        public Method method() {
            return method;
        }

        @Override
        public T method(Method method) {
            Validate.notNullParam(method, "method");

View on GitHub (pinned to 9851ac5d9c)