elastic/elasticsearch · error · IllegalArgumentException

field [{}] should contain only string or array of strings

Error message

field [{}] should contain only string or array of strings

What it means

Thrown by GeoIpProcessor.execute when the source field value is neither a String nor a List. The processor only accepts a single string IP or an array of string IPs; any other type (number, object, boolean) hits the final else branch.

Source

Thrown at modules/ingest-ip-location/src/main/java/org/elasticsearch/ingest/iplocation/GeoIpProcessor.java:144

                    }
                    return document;
                }
                if (data.isEmpty()) {
                    dataList.add(null);
                    continue;
                }
                if (firstOnly) {
                    writeGeoIpData(document, targetField, data);
                    return document;
                }
                match = true;
                dataList.add(data);
            }
            if (match) {
                writeGeoIpDataList(document, targetField, dataList);
            }
        } else {
            throw new IllegalArgumentException("field [" + field + "] should contain only string or array of strings");
        }

        return document;
    }

    @Override
    public String getType() {
        return type;
    }

    String getField() {
        return field;
    }

    String getTargetField() {
        return targetField;
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. Use a convert processor upstream to cast the field to string.
2. Correct the field path to point at the actual IP string value.
3. Add a script processor to normalize the value to a string before geoip.

Example fix

// before: client_ip is a numeric value
{
  "geoip": { "field": "client_ip", "target_field": "geo" }
}
// after: convert to string first
{
  "convert": { "field": "client_ip", "type": "string" } },
{
  "geoip": { "field": "client_ip", "target_field": "geo" }
}

// Verify the field is String or List before geoip
Object v = document.getFieldValue("client_ip", Object.class, true);
if (v != null && !(v instanceof String) && !(v instanceof List)) {
    // add a convert processor or fix the field path
}

boolean isStringOrStringArray(IngestDocument doc, String field) {
    Object v = doc.getFieldValue(field, Object.class, true);
    return v instanceof String || v instanceof List;
}

try {
    // run geoip processor
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("should contain only string or array of strings")) {
        // add a convert processor to cast to string
    } else { throw e; }
}

When it happens

Trigger: The configured field holds a scalar non-string value (e.g., a numeric IP representation, a boolean, a nested object, or a Long).

Common situations: Field type changes upstream (e.g., IP stored as a long integer). Nested objects where the field points to a map. Misconfigured field path resolving to the wrong nested structure.

Related errors

• array in field [{}] should only contain strings
• field [{}] of type [{}] cannot be cast to [{}]
• field [{}] is null, cannot extract geoip information.
• failure store document has unexpected structure, missing req
• failure store document has unexpected structure, missing req

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