elastic/elasticsearch · error · MustacheException

Exception while parsing mustache function at line {tc.line()

Error message

Exception while parsing mustache function at line {tc.line()}

What it means

Thrown by UrlEncoderCode.run() when an IOException occurs during the execution of the {{#url}}...{{/url}} function. The function captures each inner code's output to a StringWriter and URL-encodes it; if the capture or encoding step fails with IOException, it is wrapped in this MustacheException with the template line number.

Source

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

        UrlEncoderCode(TemplateContext tc, DefaultMustacheFactory df, Mustache mustache, String variable) {
            super(tc, df, mustache.getCodes(), variable);
            this.encoder = new UrlEncoder();
        }

        @Override
        public Writer run(Writer writer, List<Object> scopes) {
            if (getCodes() != null) {
                for (Code code : getCodes()) {
                    try (StringWriter capture = new StringWriter()) {
                        code.execute(capture, scopes);

                        String s = capture.toString();
                        if (s != null) {
                            encoder.encode(s, writer);
                        }
                    } catch (IOException e) {
                        throw new MustacheException("Exception while parsing mustache function at line " + tc.line(), e);
                    }
                }
            }
            return writer;
        }

        static boolean match(String variable) {
            return CODE.equalsIgnoreCase(variable);
        }
    }

    @FunctionalInterface
    interface Encoder {
        /**
         * Encodes the {@code s} string and writes it to the {@code writer} {@link Writer}.
         *
         * @param s      The string to encode
         * @param writer The {@link Writer} to which the encoded string will be written to

View on GitHub (pinned to db6a809a66)

Solutions

1. Simplify the content inside {{#url}}...{{/url}} to a single variable: {{#url}}search_term{{/url}}
2. Check the template line number in the error message to locate the failing section
3. Verify the parameter value being URL-encoded is a simple string
4. If the error persists, URL-encode the value client-side before passing it as a parameter

Example fix

// before — complex content inside url function:
{{#url}}{{#toJson}}filters{{/toJson}}{{/url}}

// after — simple variable:
{{#url}}query{{/url}}

// Validate that {{#url}} blocks contain simple variable references only
// Check template source for {{#url}} blocks with complex nested content
// and simplify to {{#url}}singleVar{{/url}}

When it happens

Trigger: Using the {{#url}}variable{{/url}} function in a search template where the inner code execution throws IOException during output capture. Since StringWriter.write() does not throw IOException, this typically indicates a failure in the inner Code's execute() method or an edge case in the encoding logic.

Common situations: Rarely encountered. Could occur if the inner code represents a complex nested structure that fails during execution. More likely seen alongside other rendering errors in deeply nested templates. The line number in the message helps pinpoint the template location.

Related errors

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

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