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

Rewrite the terms lookup as an explicit array of string terms in the filter JSON.

OrchardCMS/OrchardCore · error · ArgumentException

The terms lookup query is not supported

Error message

The terms lookup query is not supported

What it means

The terms query in this provider only supports arrays of string terms. When the field's JSON value is an object, this indicates the Elasticsearch 'terms lookup' syntax (fetching terms from another document), which Lucene's TermsFilterProvider does not implement, so it throws immediately.

Solutions

Rewrite the terms lookup as an explicit array of string terms in the filter JSON.
Fetch the referenced document/terms in application code first, then pass the resulting array.
Catch ArgumentException and surface a message that terms lookup is unsupported in Lucene query filters.

Example fix

// before
{"tags": {"index": "recipes", "id": "1", "path": "tag_ids"}}
// after
{"tags": ["tag1", "tag2"]}

Defensive patterns

Strategy: validation

Validate before calling

if (filter.Value.ValueKind == JsonValueKind.Object)
    throw new ArgumentException("terms lookup is not supported; pass an explicit array of terms");

Type guard

static bool IsSupportedTermsFilter(JsonElement el) => el.ValueKind == JsonValueKind.Array;

Try / catch

try { var query = provider.CreateFilteredQuery(context, filter); }
catch (ArgumentException ex) when (ex.Message.Contains("terms lookup"))
{ return BadRequest("Terms lookup queries are not supported by Lucene filters; use an explicit term array."); }

Prevention

Never copy Elasticsearch terms-lookup syntax into Orchard Lucene filters.
Resolve lookup documents in application code and inline the term array.
Document supported filter shapes for API consumers.

When it happens

Trigger: Calling CreateFilteredQuery with a filter like {"field": {"index": "other", "id": "1", "path": "values"}} — the Elasticsearch terms-lookup object form.

Common situations: Porting Elasticsearch queries that use terms lookup directly into Orchard Core Lucene filters without rewriting them into an explicit array of terms.

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/46ef967083ef66d6. Report an issue: GitHub.

Appendix: source

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

        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");
        }

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

        return new FilteredQuery(booleanQuery, queryFilter);
    }
}

View on GitHub (pinned to 4306c0717f)