elastic/elasticsearch · error · IllegalArgumentException

filters cannot be null or empty

Error message

filters cannot be null or empty

What it means

FilterPathBasedFilter requires at least one FilterPath. The constructor checks filters == null || filters.length == 0 and throws IllegalArgumentException. An empty filter set is meaningless for include/exclude filtering, so it is rejected up front rather than behaving as a pass-through.

Source

Thrown at libs/x-content/impl/src/main/java/org/elasticsearch/xcontent/provider/filtering/FilterPathBasedFilter.java:52

     * Marker value that should be used to indicate that none of the
     * property names/values matches one of the filter paths.
     */
    private static final TokenFilter NO_MATCHING = new TokenFilter() {
        @Override
        public String toString() {
            return "NO_MATCHING";
        }
    };

    private final FilterPath[] filters;

    private final boolean inclusive;

    private final boolean matchFieldNamesWithDots;

    public FilterPathBasedFilter(FilterPath[] filters, boolean inclusive, boolean matchFieldNamesWithDots) {
        if (filters == null || filters.length == 0) {
            throw new IllegalArgumentException("filters cannot be null or empty");
        }
        this.inclusive = inclusive;
        this.filters = filters;
        this.matchFieldNamesWithDots = matchFieldNamesWithDots;
    }

    public FilterPathBasedFilter(Set<String> filters, boolean inclusive) {
        this(FilterPath.compile(filters), inclusive, false);
    }

    /**
     * Evaluates if a property name matches one of the given filter paths.
     */
    private TokenFilter evaluate(String name, FilterPath[] filterPaths) {
        if (filterPaths != null) {
            List<FilterPath> nextFilters = new ArrayList<>();
            for (FilterPath filter : filterPaths) {
                boolean matches = filter.matches(name, nextFilters, matchFieldNamesWithDots);

View on GitHub (pinned to db6a809a66)

Solutions

1. Guard the caller: only build the filter when the set is non-empty
2. Pass null/no filter rather than an empty array if your API distinguishes them
3. Provide a meaningful default filter when the user supplied none

Example fix

// before
new FilterPathBasedFilter(new FilterPath[0], true, false); // throws
// after
FilterPath[] paths = FilterPath.compile(includes);
if (paths == null || paths.length == 0) {
    // skip filtering entirely
} else {
    new FilterPathBasedFilter(paths, true, false);
}

if (filters == null || filters.length == 0) {
    // no filtering - return identity filter or skip
    return;
}
new FilterPathBasedFilter(filters, inclusive, matchDots);

static boolean hasFilters(FilterPath[] f) {
    return f != null && f.length > 0;
}

try { new FilterPathBasedFilter(paths, true, false); }
catch (IllegalArgumentException e) { /* skip filtering */ }

When it happens

Trigger: Constructing FilterPathBasedFilter with an empty array or null filter set, or via the Set-based constructor with an empty Set (FilterPath.compile would be called on an empty set).

Common situations: Building a source_filter / filter_path request from a user query that resolved to no fields; programmatic removal of all filter entries leaving an empty collection; defaulting to empty when a config value is absent instead of falling back to a meaningful default.

Related errors

• Can't write raw bytes whose xcontent-type can't be guessed
• Expected text at {} but found {}
• q should be in [0,1], got ${q}
• q should be in [0,1], got ${q}
• Invalid value: ${x}

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