apache/incubator-seata · error · IllegalArgumentException

URL must not be null or blank

Error message

URL must not be null or blank

What it means

HttpClientUtil.watch builds a long-lived HTTP/2 watch (SSE-style) connection for the given URL using OkHttp. Before creating the client it validates the URL and throws IllegalArgumentException when the URL is null, empty, or whitespace-only, because OkHttp would otherwise fail with a less clear error deep in the request builder.

Source

Thrown at common/src/main/java/org/apache/seata/common/util/HttpClientUtil.java:285

     * @param method HTTP method (GET, POST, PUT)
     * @param eventType the class type for deserializing event data
     * @param readTimeoutSeconds read timeout in seconds (0 = infinite)
     * @param <T> the event data type
     * @return a Watch instance for receiving SSE events
     * @throws IOException if the request fails
     * @throws IllegalArgumentException if the URL is null or blank
     */
    private static <T> SeataHttpWatch<T> watch(
            String url,
            Map<String, String> headers,
            RequestBody requestBody,
            String method,
            Class<T> eventType,
            int readTimeoutSeconds)
            throws IOException {

        if (StringUtils.isBlank(url)) {
            throw new IllegalArgumentException("URL must not be null or blank");
        }

        OkHttpClient client = createHttp2WatchClient(readTimeoutSeconds);
        Request request = buildHttp2WatchRequest(url, headers, requestBody, method);
        return SeataHttpWatch.createWatch(client, request, eventType);
    }

    public static <T> SeataHttpWatch<T> watch(
            String url, Map<String, String> headers, Class<T> eventType, int readTimeoutSeconds) throws IOException {
        return watch(url, headers, null, "GET", eventType, readTimeoutSeconds);
    }

    public static <T> SeataHttpWatch<T> watch(String url, Class<T> eventType, int readTimeoutSeconds)
            throws IOException {
        return watch(url, null, null, "GET", eventType, readTimeoutSeconds);
    }

    public static <T> SeataHttpWatch<T> watchPost(

View on GitHub (pinned to e01f97c6db)

Solutions

1. Set the missing URL property in configuration before starting the client
2. Null/blank-check the URL at the call site and fail fast with a clear config-key name
3. Log the resolved URL at startup to catch empty config early

Example fix

// before
SeataHttpWatch<Event> w = HttpClientUtil.watch(url, headers, Event.class, 30);

// after
if (StringUtils.isBlank(url)) throw new IllegalStateException("watch url missing: check 'seata.watch.url' config");
SeataHttpWatch<Event> w = HttpClientUtil.watch(url, headers, Event.class, 30);

if (StringUtils.isBlank(watchUrl)) throw new ConfigurationException("watch URL not configured");
SeataHttpWatch<T> w = HttpClientUtil.watch(watchUrl, headers, eventType, timeout);

try { watch = HttpClientUtil.watch(url, headers, type, t); } catch (IllegalArgumentException e) { log.error("watch URL invalid: {}", url); throw e; }

When it happens

Trigger: Calling HttpClientUtil.watch(url, headers, eventType, readTimeoutSeconds) (or the 5-arg overload with method/RequestBody) where url is null, "", or " ". Typically the URL was assembled from configuration that was never populated.

Common situations: registry/config server address missing from application.properties (e.g. seata.console URL or a watch endpoint property left blank), or a lookup returned null and was passed straight through.

Related errors

• ip and port string cannot be empty!
• Watch request failed: {}
• not support config type:
• name can't be null
• The default branch type must be AT or XA. the value of the a

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/5cbb60374e7829ac. Report an issue: GitHub.