What causes "Mustache script result size limit exceeded" in elastic/elasticsearch?

Reduce the number of items in loop parameters — paginate or batch large parameter arrays

elastic/elasticsearch · error · ElasticsearchParseException

Mustache script result size limit exceeded

Error message

Mustache script result size limit exceeded

What it means

Thrown by MustacheExecutableScript.execute() when the rendered template output exceeds the configured size limit (mustache.max_output_size_bytes, default 1mb). The SizeLimitingStringWriter throws SizeLimitExceededException which is detected via ExceptionsHelper.unwrap() anywhere in the causal chain and converted to an ElasticsearchParseException. This is explicitly treated as a client problem and not logged.

Source

Thrown at modules/lang-mustache/src/main/java/org/elasticsearch/script/mustache/MustacheScriptEngine.java:153

        /**
         * @param template the compiled template object wrapper
         **/
        MustacheExecutableScript(Mustache template, Map<String, Object> params) {
            super(params);
            this.template = template;
            this.params = params;
        }

        @Override
        public String execute() {
            StringWriter writer = new SizeLimitingStringWriter(sizeLimit);
            try {
                template.execute(writer, params);
            } catch (Exception e) {
                // size limit exception can appear at several places in the causal list depending on script & context
                if (ExceptionsHelper.unwrap(e, SizeLimitingStringWriter.SizeLimitExceededException.class) != null) {
                    // don't log, client problem
                    throw new ElasticsearchParseException("Mustache script result size limit exceeded", e);
                }
                if (shouldLogException(e)) {
                    logger.error(() -> format("Error running %s", template), e);
                }
                throw new GeneralScriptException("Error running " + template, e);
            }
            return writer.toString();
        }

        public boolean shouldLogException(Throwable e) {
            return e.getCause() != null && e.getCause() instanceof MustacheInvalidParameterException == false;
        }
    }

}

View on GitHub (pinned to db6a809a66)

Solutions

Reduce the number of items in loop parameters — paginate or batch large parameter arrays
Increase the size limit via cluster setting: PUT /_cluster/settings {"persistent": {"mustache.max_output_size_bytes": "5mb"}}
Simplify the template structure to produce less output per parameter item
If the template generates a terms query with thousands of values, consider using a terms lookup or terms set query instead

Example fix

// before — cluster default (1mb) too small for large template output:
// (template rendering fails at runtime)

// after — increase the limit via cluster settings:
PUT /_cluster/settings
{
  "persistent": {
    "mustache.max_output_size_bytes": "5mb"
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// Estimate rendered output size before execution
int estimateOutputSize(String template, Map<String, Object> params) {
    // rough estimate: render to a bounded buffer and check
    // or estimate based on array param sizes * per-item template expansion
    int estimated = 0;
    for (var e : params.entrySet()) {
        if (e.getValue() instanceof Collection<?> c) {
            estimated += c.size() * 100; // rough per-item cost
        }
    }
    return estimated;
}
// compare against mustache.max_output_size_bytes before executing

Try / catch

// Catch ElasticsearchParseException for size limit exceeded
try {
    String result = templateExecutable.execute();
} catch (ElasticsearchParseException e) {
    if (e.getMessage().contains("size limit")) {
        // reduce params or increase limit
        log.warn("Template output exceeded size limit, reduce input size or increase mustache.max_output_size_bytes");
    }
    throw e;
}

Prevention

Paginate large array parameters instead of sending all at once
Monitor rendered output sizes for templates with loops
Adjust mustache.max_output_size_bytes cluster setting if legitimate large outputs are expected
Use terms lookup or terms set queries instead of expanding huge arrays in templates

When it happens

Trigger: Executing a search template whose rendered output (after parameter substitution) exceeds the mustache.max_output_size_bytes limit. Common with templates that loop over large arrays, generate large term queries, or produce verbose JSON. The size limit applies to the final rendered string, not the template source or input params.

Common situations: Templates with {{#items}} loops over large arrays. Templates generating many terms clauses from a large parameter list. Default 1mb limit being too small for legitimate large queries. Increasing parameter array sizes without adjusting the output size limit.

Related errors

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