OrchardCMS/OrchardCore · error · ArgumentException

Invalid terms query

Error message

Invalid terms query

What it means

TermsQueryProvider only accepts a JSON array of values for the terms field. Any JSON kind other than Array or Object (string, number, bool, null) falls into the default case and throws ArgumentException.

Solutions

1. Wrap the value in a JSON array: {"terms": {"myField": ["singleValue"]}}.
2. Validate the query JSON shape before passing it to the provider.
3. If you only need one term, use a Term-based query (e.g. term query) instead of terms.

Example fix

// before
{"terms": {"category": "news"}}
// after
{"terms": {"category": ["news"]}}

if (terms.ValueKind != JsonValueKind.Array)
    throw new InvalidOperationException("Terms query value must be a JSON array of term values.");

static bool IsTermsArray(JsonElement el) => el.ValueKind == JsonValueKind.Array && el.GetArrayLength() > 0;

catch (ArgumentException ex) when (ex.Message == "Invalid terms query")
{
    // wrap single scalar into an array and retry, or report invalid query
}

When it happens

Trigger: Calling CreateQuery with a terms query whose field value is a scalar string/number/boolean/null, e.g. {"terms": {"myField": "singleValue"}}.

Common situations: Hand-writing Lucene query JSON and supplying a single term as a plain string instead of an array; programmatic query builders appending one value without wrapping it in a list.

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

• Query DSL requires a [query] property
• Invalid query
• Missing value in match phrase query
• Invalid wildcard query
• Prefix query misses prefix value

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

Appendix: source

Thrown at src/OrchardCore/OrchardCore.Lucene.Core/QueryProviders/TermsQueryProvider.cs:40

        switch (first.Value.GetValueKind())
        {
            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");
        }

        return boolQuery;
    }
}

View on GitHub (pinned to 4306c0717f)