OrchardCMS/OrchardCore · error · ArgumentException

Invalid terms query

Error message

Invalid terms query

What it means

This is the fall-through case of TermsFilterProvider.CreateFilteredQuery: the field's JSON value is neither an array nor an object (e.g. a bare string, number, boolean, or null), which cannot be interpreted as a terms query, so an ArgumentException is thrown.

Solutions

1. Wrap the scalar in a JSON array: {"field": ["value"]}.
2. Use the term filter provider instead of the terms provider for single scalar values.
3. Validate the filter shape (value must be an array of strings) before calling CreateFilteredQuery.

Example fix

// before
{"status": "published"}
// after
{"status": ["published"]}

if (filter.Value.ValueKind is not (JsonValueKind.Array or JsonValueKind.Object))
    throw new ArgumentException("terms filter value must be an array of strings");

static bool IsTermsShape(JsonElement el) => el.ValueKind == JsonValueKind.Array;
static bool IsTermShape(JsonElement el) => el.ValueKind == JsonValueKind.String;

try { var query = provider.CreateFilteredQuery(context, filter); }
catch (ArgumentException ex) { return BadRequest($"Invalid terms query shape: {ex.Message}"); }

When it happens

Trigger: Calling CreateFilteredQuery with a filter like {"field": "value"} or {"field": 42} where the value is not a JSON array (terms list) or object (unsupported lookup).

Common situations: Confusing the 'term' query form (single scalar) with 'terms' (array); code generators emitting scalars for single-element term lists; malformed filter JSON from client templates.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid term in terms query
• Invalid wildcard query
• Invalid fuzzy query
• Invalid query
• Prefix query misses prefix value

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/ff56d2acb20eceb8. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore/OrchardCore.Lucene.Core/QueryProviders/Filters/TermsFilterProvider.cs:47

        {
            case JsonValueKind.Array:

                foreach (var item in first.Value.AsArray())
                {
                    if (item.GetValueKind() != JsonValueKind.String)
                    {
                        throw new ArgumentException($"Invalid term in terms query");
                    }

                    boolQuery.Add(new TermQuery(new Term(field, item.Value<string>())), Occur.SHOULD);
                }

                break;

            case JsonValueKind.Object:
                throw new ArgumentException("The terms lookup query is not supported");

            default: throw new ArgumentException("Invalid terms query");
        }

        booleanQuery.Add(boolQuery, Occur.MUST);
        var queryFilter = new QueryWrapperFilter(boolQuery);

        return new FilteredQuery(booleanQuery, queryFilter);
    }
}

View on GitHub (pinned to 4306c0717f)