elastic/elasticsearch · error · IllegalArgumentException

bufferLimit must be greater than 0

Error message

bufferLimit must be greater than 0

What it means

HeapBufferedAsyncResponseConsumer buffers the response body on the heap up to a fixed byte limit. The constructor rejects bufferLimit <= 0 because a zero/negative buffer cannot hold any entity, making the consumer useless; the message is a hard precondition with no recovery inside the constructor.

Source

Thrown at client/rest/src/main/java/org/elasticsearch/client/HeapBufferedAsyncResponseConsumer.java:55

/**
 * Default implementation of {@link org.apache.http.nio.protocol.HttpAsyncResponseConsumer}. Buffers the whole
 * response content in heap memory, meaning that the size of the buffer is equal to the content-length of the response.
 * Limits the size of responses that can be read based on a configurable argument. Throws an exception in case the entity is longer
 * than the configured buffer limit.
 */
public class HeapBufferedAsyncResponseConsumer extends AbstractAsyncResponseConsumer<HttpResponse> {

    private final int bufferLimitBytes;
    private volatile HttpResponse response;
    private volatile SimpleInputBuffer buf;

    /**
     * Creates a new instance of this consumer with the provided buffer limit
     */
    public HeapBufferedAsyncResponseConsumer(int bufferLimit) {
        if (bufferLimit <= 0) {
            throw new IllegalArgumentException("bufferLimit must be greater than 0");
        }
        this.bufferLimitBytes = bufferLimit;
    }

    /**
     * Get the limit of the buffer.
     */
    public int getBufferLimit() {
        return bufferLimitBytes;
    }

    @Override
    protected void onResponseReceived(HttpResponse httpResponse) throws HttpException, IOException {
        this.response = httpResponse;
    }

    @Override
    protected void onEntityEnclosed(HttpEntity entity, ContentType contentType) throws IOException {

View on GitHub (pinned to db6a809a66)

Solutions

1. Pass a positive byte limit (e.g. a few MB) when constructing the consumer or its factory.
2. Validate/derive the limit from configuration with Math.max(1, ...) and fix the config default.
3. Prefer using the RestClientBuilder helper which supplies a sane default consumer factory.

Example fix

// before
new HeapBufferedAsyncResponseConsumer(configuredLimit); // configuredLimit=0
// after
new HeapBufferedAsyncResponseConsumer(Math.max(1, configuredLimit));

int safeLimit = Math.max(1, configuredBufferLimit);
new HeapBufferedAsyncResponseConsumer(safeLimit);

When it happens

Trigger: Instantiating HeapBufferedAsyncResponseConsumer(0) or with a negative value, usually via a misconfigured RestClientBuilder.setMaxRetryTimeoutMillis / setHttpAsyncResponseConsumerFactory that derives the limit from a config that resolved to 0.

Common situations: A config property for response buffer size is unset and defaults to 0; arithmetic that produces <= 0; passing a byte count parsed from a malformed string.

Related errors

• host cannot be null
• maxAttempts must be >= 1 but was [{}]
• baseBackoffMillis must be >= 0 but was [{}]
• can't compare DeadHostStates holding different time supplier
• entity content is too long [{}] for the configured buffer li

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