What causes "Parameter [{name}] is missing" in elastic/elasticsearch?

Provide all parameters referenced in the template in the params object — check for typos in the parameter name from the error message

elastic/elasticsearch · error · MustacheInvalidParameterException

Parameter [{name}] is missing

Error message

Parameter [{name}] is missing

What it means

Thrown by DetectMissingParamsGuardedBinding when detect_missing_params is enabled and a template references a parameter ({{paramName}}) that was not provided in the params object. This is an opt-in strict mode: when the Script option 'detect_missing_params' is set to 'true', the CustomReflectionObjectHandler uses a GuardedBinding that checks each variable binding and throws MustacheInvalidParameterException if the wrapper is a MissingWrapper for a ValueCode (a plain variable reference).

Source

Thrown at modules/lang-mustache/src/main/java/org/elasticsearch/script/mustache/CustomReflectionObjectHandler.java:92

         * that is, with the permissions we're running with, it would always return null ('not found!') or throw
         * an exception ('found, but you cannot do this!') -- so by overriding to null we're effectively saying
         * "you will never find success going down this path, so don't bother trying"
         */
        return null;
    }

    private static final class DetectMissingParamsGuardedBinding extends GuardedBinding {
        private final Code code;

        DetectMissingParamsGuardedBinding(ObjectHandler oh, String name, TemplateContext tc, Code code) {
            super(oh, name, tc, code);
            this.code = code;
        }

        protected synchronized Wrapper getWrapper(String name, List<Object> scopes) {
            Wrapper wrapper = super.getWrapper(name, scopes);
            if (wrapper instanceof MissingWrapper && code instanceof ValueCode) {
                throw new MustacheInvalidParameterException("Parameter [" + name + "] is missing");
            }
            return wrapper;
        }
    }

    private static final class ArrayMap extends AbstractMap<Object, Object> implements Iterable<Object> {

        private final Object array;
        private final int length;

        ArrayMap(Object array) {
            this.array = array;
            this.length = Array.getLength(array);
        }

        @Override
        public Object get(Object key) {
            if ("size".equals(key)) {

View on GitHub (pinned to db6a809a66)

Solutions

Provide all parameters referenced in the template in the params object — check for typos in the parameter name from the error message
If the parameter is optional, use a conditional section {{#param}}...{{/param}} instead of a bare {{param}} reference
Disable detect_missing_params if you want missing parameters to render as empty (set to false or omit the option)
Audit the template source for all {{variable}} references and cross-check against the params keys

Example fix

// before — missing parameter with detect_missing_params:
POST /_search/template
{
  "source": { "query": { "term": { "category": "{{category}}" } } },
  "params": { "cat": "books" },
  "detect_missing_params": true
}

// after — match the parameter name:
POST /_search/template
{
  "source": { "query": { "term": { "category": "{{category}}" } } },
  "params": { "category": "books" },
  "detect_missing_params": true
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate all template variables are present in params before execution
Set<String> extractTemplateVars(String templateSource) {
    // extract all {{varName}} references (not sections)
    Set<String> vars = new HashSet<>();
    Pattern p = Pattern.compile("\\{\{(?![#/^/>&])([^}]+)\}\}");
    Matcher m = p.matcher(templateSource);
    while (m.find()) vars.add(m.group(1).trim());
    return vars;
}
// before execution: assert params.keySet().containsAll(extractTemplateVars(source))

Try / catch

// When detect_missing_params is enabled, catch MustacheInvalidParameterException
try {
    template.execute(writer, params);
} catch (MustacheInvalidParameterException e) {
    // parameter is missing — provide a default or fix the params
    log.warn("Missing template parameter: {}", e.getMessage());
}

Prevention

Cross-check all {{variable}} references against params keys before execution
Use {{#param}}...{{/param}} conditional sections for optional parameters
Enable detect_missing_params in development to catch typos early
Keep a registry of required parameters for each stored template

When it happens

Trigger: Executing a search template with {"detect_missing_params": true} in the script options, where the template references {{field_name}} but no matching key exists in the params object. For example, template source contains {{category}} but params is {"categories": "books"} (typo or missing key).

Common situations: Typos in parameter names between template and params. Forgetting to pass a required parameter. Dynamically generated templates where some branches reference params not always supplied. Enabling detect_missing_params for stricter validation during development but forgetting to update params when adding new template variables.

Related errors

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