elastic/elasticsearch · error · MustacheException

Exception while parsing mustache function [{}] at line {}

Error message

Exception while parsing mustache function [{}] at line {}

What it means

Thrown by CustomCode.extractVariableName() when an IOException occurs while capturing the variable name from a custom mustache function block at compile time. This wraps the I/O failure (from writing to a StringWriter during code identity/capture) in a MustacheException. Since the capture uses an in-memory StringWriter, an actual IOException here is extremely rare and indicates an internal failure.

Source

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

         * At compile time, this function extracts the name of the variable:
         * {{#toJson}}variable_name{{/toJson}}
         */
        protected static String extractVariableName(String fn, Mustache mustache, TemplateContext tc) {
            Code[] codes = mustache.getCodes();
            if (codes == null || codes.length != 1) {
                throw new MustacheException("Mustache function [" + fn + "] must contain one and only one identifier");
            }

            try (StringWriter capture = new StringWriter()) {
                // Variable name is in plain text and has type WriteCode
                if (codes[0] instanceof WriteCode) {
                    codes[0].execute(capture, List.of());
                } else {
                    codes[0].identity(capture);
                }
                return capture.toString();
            } catch (IOException e) {
                throw new MustacheException("Exception while parsing mustache function [" + fn + "] at line " + tc.line(), e);
            }
        }
    }

    /**
     * This function renders {@link Iterable} and {@link Map} as their JSON representation
     */
    private static class ToJsonCode extends CustomCode {

        private static final String CODE = "toJson";

        ToJsonCode(TemplateContext tc, DefaultMustacheFactory df, Mustache mustache, String variable) {
            super(tc, df, mustache, CODE);
            if (CODE.equalsIgnoreCase(variable) == false) {
                throw new MustacheException("Mismatch function code [" + CODE + "] cannot be applied to [" + variable + "]");
            }
        }

View on GitHub (pinned to db6a809a66)

Solutions

1. Simplify the function block to a bare variable name and retry
2. Check for memory pressure or OOM conditions on the node
3. Report as a bug if reproducible with a minimal template — include the full template source and the line number from the error
4. As a workaround, avoid the custom function and inline the value directly

// Catch ScriptException (wrapping MustacheException) at compile time
try {
    engine.compile(name, source, context, options);
} catch (ScriptException e) {
    // check for internal I/O failure during parsing
    log.error("Template compilation failed: {}", e.getMessage(), e);
}

When it happens

Trigger: An internal I/O failure during the compile-time extraction of a variable name from a toJson, join, or url function block. The StringWriter used for capture should not throw IOException under normal circumstances; this path is a defensive catch for unexpected internal errors.

Common situations: Virtually never seen in production. Could theoretically occur under extreme memory pressure or if a mustache Code implementation's execute/identity method throws an unexpected IOException. More likely indicates a bug in a custom mustache extension or an edge case in the mustache library itself.

Related errors

• Unable to encode value
• Mustache function [{}] must contain one and only one identif
• Failed to extract delimiter for join function
• Exception while parsing mustache function at line {tc.line()
• {ex.getMessage()}

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