elastic/elasticsearch · error · IllegalArgumentException

hosts must not be null nor empty

Error message

hosts must not be null nor empty

What it means

RestClient.builder(HttpHost...) requires at least one host to route requests to; a null or empty array makes the client structurally invalid (no node tuple, no round-robin). The guard rejects both null and zero-length arrays up front.

Source

Thrown at client/rest/src/main/java/org/elasticsearch/client/RestClient.java:216

     * <p>
     * Prefer this to {@link #builder(HttpHost...)} if you have metadata up front about the nodes.
     * If you don't either one is fine.
     */
    public static RestClientBuilder builder(Node... nodes) {
        return new RestClientBuilder(nodes == null ? null : Arrays.asList(nodes));
    }

    /**
     * Returns a new {@link RestClientBuilder} to help with {@link RestClient} creation.
     * Creates a new builder instance and sets the nodes that the client will send requests to.
     * <p>
     * You can use this if you do not have metadata up front about the nodes. If you do, prefer
     * {@link #builder(Node...)}.
     * @see Node#Node(HttpHost)
     */
    public static RestClientBuilder builder(HttpHost... hosts) {
        if (hosts == null || hosts.length == 0) {
            throw new IllegalArgumentException("hosts must not be null nor empty");
        }
        List<Node> nodes = Arrays.stream(hosts).map(Node::new).collect(Collectors.toList());
        return new RestClientBuilder(nodes);
    }

    /**
     * Get the underlying HTTP client.
     */
    public HttpAsyncClient getHttpClient() {
        return this.client;
    }

    /**
     * Replaces the nodes with which the client communicates.
     */
    public synchronized void setNodes(Collection<Node> nodes) {
        if (nodes == null || nodes.isEmpty()) {
            throw new IllegalArgumentException("nodes must not be null or empty");

View on GitHub (pinned to db6a809a66)

Solutions

1. Ensure the host list is non-empty before building — validate config at load time and fail with a clearer message.
2. Fall back to a known default host (e.g. localhost:9200) only if that is your intended policy.
3. If discovery legitimately has zero hosts, delay client creation until at least one host resolves.

Example fix

// before
HttpHost[] hosts = config.getHosts(); // empty
RestClient.builder(hosts); // throws
// after
if (hosts == null || hosts.length == 0) throw new IllegalStateException("no ES hosts configured");
RestClient.builder(hosts);

if (hosts == null || hosts.length == 0) throw new IllegalStateException("no Elasticsearch hosts configured");
RestClient.builder(hosts);

static boolean hasHosts(HttpHost[] h) { return h != null && h.length > 0; }

When it happens

Trigger: Calling RestClient.builder() with an empty varargs list, or passing a null HttpHost[] from config that resolved to no hosts.

Common situations: Configuration source (env/properties) returned zero hosts; a service-discovery lookup produced an empty list; programmatic helper that built the array conditionally and ended up empty.

Related errors

• cloudId {} must begin with a human readable identifier follo
• cloudId {} did not decode to a cluster identifier correctly
• cloudId {} does not contain a valid port number
• nodes must not be null or empty
• nodes must not be null or empty

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