What causes "The terms lookup query is not supported" in OrchardCMS/OrchardCore?

Replace the object value with an explicit JSON array of term values, e.g. {"myField": ["a","b"]}.

OrchardCMS/OrchardCore · error · ArgumentException

The terms lookup query is not supported

Error message

The terms lookup query is not supported

What it means

Lucene's TermsQueryProvider builds a terms query from a JSON value. When the JSON value for the field is an object, the provider interprets it as an Elasticsearch-style terms-lookup query, which Lucene's TermsQuery cannot express, so it throws ArgumentException immediately.

Solutions

Replace the object value with an explicit JSON array of term values, e.g. {"myField": ["a","b"]}.
Fetch the terms yourself (query the source document first) and inline the values as an array.
If terms lookup is essential, use a query provider/store that supports it (e.g. Elasticsearch integration) instead of Lucene.

Example fix

// before
{"query": {"terms": {"role": {"id": "user1", "path": "roles"}}}}
// after
{"query": {"terms": {"role": ["editor", "author"]}}}

Defensive patterns

Strategy: validation

Validate before calling

if (termsValue.ValueKind == JsonValueKind.Object)
    throw new InvalidOperationException("Terms lookup (object value) is not supported by Lucene terms query; supply an array of values.");

Type guard

static bool IsSupportedTermsValue(JsonElement el) => el.ValueKind == JsonValueKind.Array || el.ValueKind == JsonValueKind.String;

Try / catch

catch (ArgumentException ex) when (ex.Message.Contains("terms lookup"))
{
    // rewrite query or surface 'unsupported query' to user
}

Prevention

Never port Elasticsearch terms-lookup queries verbatim into Lucene query JSON.
Resolve referenced terms client-side and inline them as arrays.
Add a query-JSON pre-validator for Lucene query providers.

When it happens

Trigger: Calling CreateQuery with a terms query whose JSON value for the field is a JSON object (JsonValueKind.Object), e.g. {"terms": {"myField": {"id": "doc1", "path": "some.path"}}}.

Common situations: Porting Elasticsearch queries that use terms lookup (fetching terms from another document) directly into Orchard Core Lucene queries without rewriting them into an explicit list of values.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

        var boolQuery = new BooleanQuery();

        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)