What causes "entity content is too long [{}] for the configured buffer limit [{}]" in elastic/elasticsearch?

Raise the buffer limit on RestClientBuilder (setHttpAsyncResponseConsumerFactory with a larger HeapBufferedAsyncResponseConsumer) to fit the largest expected response.

elastic/elasticsearch · error · ContentTooLongException

entity content is too long [{}] for the configured buffer li

Error message

entity content is too long [{}] for the configured buffer limit [{}]

What it means

In onEntityEnclosed, HeapBufferedAsyncResponseConsumer checks the incoming HttpEntity's declared content length against bufferLimitBytes and throws ContentTooLongException when len > bufferLimitBytes. This protects the JVM heap by refusing to buffer an oversized response body before allocation; both the actual length and the configured limit are reported.

Source

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

    }

    /**
     * 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 {
        long len = entity.getContentLength();
        if (len > bufferLimitBytes) {
            throw new ContentTooLongException(
                "entity content is too long [" + len + "] for the configured buffer limit [" + bufferLimitBytes + "]"
            );
        }
        if (len < 0) {
            len = 4096;
        }
        this.buf = new SimpleInputBuffer((int) len, getByteBufferAllocator());
        this.response.setEntity(new ContentBufferEntity(entity, this.buf));
    }

    /**
     * Returns the instance of {@link ByteBufferAllocator} to use for content buffering.
     * Allows to plug in any {@link ByteBufferAllocator} implementation.
     */
    protected ByteBufferAllocator getByteBufferAllocator() {
        return HeapByteBufferAllocator.INSTANCE;
    }

View on GitHub (pinned to db6a809a66)

Solutions

Raise the buffer limit on RestClientBuilder (setHttpAsyncResponseConsumerFactory with a larger HeapBufferedAsyncResponseConsumer) to fit the largest expected response.
Reduce the response size: paginate (search_after / scroll), narrow the query, or request fewer fields.
Stream the response instead of buffering it if the consumer supports it.

Example fix

// before: default 100MB limit, query returns 250MB
RestClientBuilder.builder(host).setHttpAsyncResponseConsumerFactory(
    new HttpAsyncResponseConsumerFactory.HeapBuffered(100 * 1024 * 1024));
// after
RestClientBuilder.builder(host).setHttpAsyncResponseConsumerFactory(
    new HttpAsyncResponseConsumerFactory.HeapBuffered(512 * 1024 * 1024));

Defensive patterns

Strategy: validation

Validate before calling

// Size the buffer to the largest expected response payload (bytes):
long expectedMax = estimateMaxResponseBytes();
int limit = (int) Math.min(Integer.MAX_VALUE, Math.max(1, expectedMax));
RestClientBuilder b = RestClient.builder(host)
    .setHttpAsyncResponseConsumerFactory(new HttpAsyncResponseConsumerFactory.HeapBuffered(limit));

Try / catch

try {
    Response r = client.performRequest(req);
} catch (ResponseException | ContentTooLongException e) {
    // narrow query / paginate / raise limit and retry
}

Prevention

Right-size queries: use pagination (search_after/scroll), narrow filters, project fewer fields.
Set the heap buffer limit based on measured peak response size, with headroom.
Monitor for ContentTooLongException in production to catch runaway queries early.

When it happens

Trigger: An Elasticsearch node returns a response whose Content-Length exceeds the configured heap buffer limit — e.g. a large scroll/search response, a bulk index of oversized docs, or a _search response with many hits while the client buffer limit is small.

Common situations: Default buffer limit too small for the workload (large aggregations, scroll contexts, snapshot metadata); a misconfigured limit; a query that accidentally returns far more data than expected.

Related errors

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