elastic/elasticsearch · error · MustacheException

Cannot expand '%s' because partial templates are not support

Error message

Cannot expand '%s' because partial templates are not supported

What it means

Thrown by CustomMustacheVisitor.partial() when a Mustache template uses the partial template syntax ({{> name}} or {{>"name"}}). Elasticsearch's mustache implementation deliberately does not support partial templates because templates are provided as inline strings, not resolved from files or classpath. The factory constructor passes resourceName -> null to DefaultMustacheFactory to prevent file-based resolution.

Source

Thrown at modules/lang-mustache/src/main/java/org/elasticsearch/script/mustache/CustomMustacheFactory.java:145

        public void iterable(TemplateContext templateContext, String variable, Mustache mustache) {
            if (ToJsonCode.match(variable)) {
                list.add(new ToJsonCode(templateContext, df, mustache, variable));
            } else if (JoinerCode.match(variable)) {
                list.add(new JoinerCode(templateContext, df, mustache));
            } else if (CustomJoinerCode.match(variable)) {
                list.add(new CustomJoinerCode(templateContext, df, mustache, variable));
            } else if (UrlEncoderCode.match(variable)) {
                list.add(new UrlEncoderCode(templateContext, df, mustache, variable));
            } else {
                list.add(new IterableCode(templateContext, df, mustache, variable));
            }
        }

        @Override
        public void partial(TemplateContext tc, String variable, String indent) {
            // throwing a mustache exception here is important because this gets caught, handled (closing readers, etc.),
            // and re-thrown in the mustache parser itself
            throw new MustacheException(Strings.format("Cannot expand '%s' because partial templates are not supported", variable));
        }

        @Override
        public void dynamicPartial(TemplateContext tc, final String variable, String indent) {
            // throwing a mustache exception here is important because this gets caught, handled (closing readers, etc.),
            // and re-thrown in the mustache parser itself
            throw new MustacheException(Strings.format("Cannot expand '%s' because dynamic partial templates are not supported", variable));
        }
    }

    /**
     * Base class for custom Mustache functions
     */
    private abstract static class CustomCode extends IterableCode {

        private final String code;

        CustomCode(TemplateContext tc, DefaultMustacheFactory df, Mustache mustache, String code) {

View on GitHub (pinned to db6a809a66)

Solutions

1. Remove all {{> ...}} partial references from the template — Elasticsearch does not support them
2. Inline any shared content directly into the template body
3. If you need reusable template fragments, store them client-side and concatenate before sending to Elasticsearch
4. Use stored scripts (PUT /_scripts/<id>) to save and reference entire templates, but note that partial inclusion between stored scripts is still not supported

Example fix

// before — template source with partial:
{"query": {"bool": {"must": [{{> filter_clause}}]}}}

// after — inline the partial content:
{"query": {"bool": {"must": [{"term": {"status": "{{status}}"}}]}}}

// Validate template source for partial syntax before submission
String templateSource = "...";
if (templateSource.contains("{{>") || templateSource.contains("{{>")) {
    throw new IllegalArgumentException("Partial templates ({{> ...}}) are not supported in Elasticsearch");
}

When it happens

Trigger: Including a partial template reference in a search template. For example, a template source containing {{> header}} or {{> "shared_clause"}}. The mustache parser invokes the visitor's partial() method during compilation, which immediately throws.

Common situations: Porting a mustache template from another system (like a web framework) that relies on partials for modularity. Attempting to share template fragments across multiple search templates via partial includes. Copying mustache syntax examples from generic mustache documentation.

Related errors

• Cannot expand '%s' because dynamic partial templates are not
• Unable to encode value
• No encoder found for media type [{}]
• Mustache function [{}] must contain one and only one identif
• Failed to convert object to JSON

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