elastic/elasticsearch · error · IllegalArgumentException

Variable [{}] does not follow an allowed format of either do

Error message

Variable [{}] does not follow an allowed format of either doc['field'] or doc['field'].method()

What it means

Thrown in getDocValueSource() when the variable has more than 3 parts and does not match the date accessor pattern (doc['field'].date.xxx or doc['field'].getDate.xxx). The only valid 4-part form is date object access; anything else triggers this error.

Source

Thrown at modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionScriptEngine.java:436

                    "Only member variables or member methods may be accessed on a field when not accessing the field directly"
                );
            }
        }
        // true if the variable is of type doc['field'].date.xxx
        boolean dateAccessor = false;
        if (parts.length > 3) {
            // access to the .date "object" within the field
            if (parts.length == 4 && ("date".equals(parts[2].text) || "getDate".equals(parts[2].text))) {
                if (parts[3].type == VariableContext.Type.METHOD) {
                    methodname = parts[3].text;
                    dateAccessor = true;
                } else if (parts[3].type == VariableContext.Type.MEMBER) {
                    variablename = parts[3].text;
                    dateAccessor = true;
                }
            }
            if (dateAccessor == false) {
                throw new IllegalArgumentException(
                    "Variable [" + variable + "] does not follow an allowed format of either doc['field'] or doc['field'].method()"
                );
            }
        }

        String fieldname = parts[1].text;
        MappedFieldType fieldType = lookup.fieldType(fieldname);

        if (fieldType == null) {
            throw new ParseException("Field [" + fieldname + "] does not exist in mappings", 5);
        }

        IndexFieldData<?> fieldData = lookup.getForField(fieldType, MappedFieldType.FielddataOperation.SEARCH);
        final DoubleValuesSource valueSource;
        if (fieldType instanceof GeoPointFieldType) {
            // geo
            if (methodname == null) {
                valueSource = GeoField.getVariable(fieldData, fieldname, variablename);

View on GitHub (pinned to db6a809a66)

Solutions

1. Limit field access to at most 3 parts: doc['field'].value or doc['field'].method().
2. For date accessors, use the 4-part pattern: doc['field'].date.<property> — valid properties include year, month, day, etc.
3. Split chained access into separate variables in the expression and combine arithmetically.
4. Switch to Painless for complex nested field access.

Example fix

// before: unsupported chained access
"source": "doc['location'].lat.lon"
// after: access each property separately
"source": "doc['location'].lat + doc['location'].lon"

// Validate that chained access beyond doc['field'].member is only for date objects
// Correct: doc['field'].date.year, doc['field'].getDate.year
// Incorrect: doc['field'].value.foo, doc['field'].lat.lon
// Check expression source for paths with more than 3 segments that aren't date accessors

try {
    engine.compile(scriptName, scriptSource, context, params);
} catch (ScriptException e) {
    if (e.getCause() instanceof IllegalArgumentException
        && e.getCause().getMessage().contains("does not follow an allowed format")) {
        logger.error("Expression variable format invalid — use doc['field'] or doc['field'].method()");
        // The variable name is in the error message
    }
    throw e;
}

When it happens

Trigger: Chaining more than one accessor on a field in an unsupported way — e.g., doc['field'].value.foo or doc['field'].lat.lon. Only doc['field'].date.<member/method> is valid for 4-part paths.

Common situations: Attempting nested property access that isn't supported; trying to chain geo point accessors (doc['field'].lat.lon instead of doc['field'].lat and doc['field'].lon separately); misunderstanding the date object accessor pattern.

Related errors

• Variable 'doc' must be used with a specific field like: doc[
• Only member variables or member methods may be accessed on a
• Unknown variable [{}]
• Can't advance to doc using {}
• Error evaluating {}

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