elastic/elasticsearch · error · IllegalArgumentException

nodes must not be null or empty

Error message

nodes must not be null or empty

What it means

Constructor guard on RestClientBuilder: the host list passed to HttpHost.create / RestClient.builder(...) must be non-null and contain at least one entry. An empty/null list is rejected immediately because the client has nowhere to send requests.

Source

Thrown at client/rest/src/main/java/org/elasticsearch/client/RestClientBuilder.java:136

        META_HEADER_VALUE = "es="
            + metaVersion
            + ",jv="
            + System.getProperty("java.specification.version")
            + ",t="
            + metaVersion
            + ",hc="
            + (httpClientVersion == null ? "" : httpClientVersion.getRelease())
            + LanguageRuntimeVersions.getRuntimeMetadata();
    }

    /**
     * Creates a new builder instance and sets the hosts that the client will send requests to.
     *
     * @throws IllegalArgumentException if {@code nodes} is {@code null} or empty.
     */
    RestClientBuilder(List<Node> nodes) {
        if (nodes == null || nodes.isEmpty()) {
            throw new IllegalArgumentException("nodes must not be null or empty");
        }
        for (Node node : nodes) {
            if (node == null) {
                throw new IllegalArgumentException("node cannot be null");
            }
        }
        this.nodes = nodes;
    }

    /**
     * Sets the default request headers, which will be sent along with each request.
     * <p>
     * Request-time headers will always overwrite any default headers.
     *
     * @throws NullPointerException if {@code defaultHeaders} or any header is {@code null}.
     */
    public RestClientBuilder setDefaultHeaders(Header[] defaultHeaders) {
        Objects.requireNonNull(defaultHeaders, "defaultHeaders must not be null");

View on GitHub (pinned to db6a809a66)

Solutions

1. Validate your host source before calling RestClient.builder and fail fast with a clear config error.
2. Provide at least one HttpHost: RestClient.builder(new HttpHost("localhost", 9200)).
3. Check the env var / property supplying hosts is non-empty.

Example fix

// before
List<HttpHost> hosts = loadFromConfig(); // returned []
RestClient.builder(hosts.toArray(new HttpHost[0]));
// after
List<HttpHost> hosts = loadFromConfig();
if (hosts.isEmpty()) throw new IllegalStateException("no ES hosts configured");
RestClient.builder(hosts.toArray(new HttpHost[0]));

if (hosts == null || hosts.isEmpty()) throw new IllegalArgumentException("configure at least one ES host");
RestClient.builder(hosts.toArray(new HttpHost[0]));

When it happens

Trigger: Calling RestClient.builder() with no vararg hosts, or builder(List) with an empty list; programmatically building the list from config that resolved to nothing.

Common situations: Configuration source returned zero hosts (empty env var, blank 'ES_HOSTS'); list built by filtering that excluded all entries; mis-ordered builder steps.

Related errors

• hosts must not be null nor empty
• node cannot be null
• pathPrefix must not be empty
• pathPrefix is malformed. consecutive slashes are not allowed
• classname is a required setting for esplugin

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/e3141ef87d4a1342. Report an issue: GitHub.