elsa-workflows/elsa-core · error · DocumentQueryNotIndexedException

No declared index exists for storage unit

Error message

No declared index exists for storage unit '{query.StorageUnit}' and fields '{string.Join(", ", fields.Order())}'.

What it means

DocumentIndexMatcher.FindMatchingIndex requires that a document collection declares an index whose exact ordered field list matches the sorted filter fields of the query. If no such single index exists, it throws DocumentQueryNotIndexedException, telling you the query cannot be executed against the declared indexes.

Solutions

1. Add a matching index to the storage unit whose Fields exactly match the query filter fields (ordinal-ordered).
2. Adjust the query filters to exactly match an existing declared index.
3. Declare a composite index covering all filtered fields in the same ordinal order the matcher compares.

Example fix

// before
// query filters: { Status, Name } but only index on [Status] exists
builder.Table("WorkflowInstances", t => t.HasIndex("IX_Status", i => i.Fields("Status")));
// after
builder.Table("WorkflowInstances", t => t.HasIndex("IX_Status_Name", i => i.Fields("Status", "Name")));

var filterFields = query.Filters.Keys.Order(StringComparer.Ordinal).ToArray();
var indexed = collection.Indexes.Any(i => i.Fields.Order(StringComparer.Ordinal).SequenceEqual(filterFields, StringComparer.Ordinal));
if (!indexed) throw new InvalidOperationException("No index covers query filter fields.");

try { var idx = DocumentIndexMatcher.FindMatchingIndex(collection, query); }
catch (DocumentQueryNotIndexedException ex) { /* add index or rewrite query */ }

When it happens

Trigger: Executing a DocumentQuery whose filter fields do not exactly equal (as an ordered set, ordinal-compared) the Fields of any index in collection.Indexes — e.g. filtering on Status alone when only a composite (Status, Name) index is declared, or on fields in a different order than declared.

Common situations: Changing query filters after indexes were designed; forgetting to declare an index for a new query; case or ordering differences between filter keys and index fields.

Related errors

• No declared index exists for storage unit
• Storage unit ' ' requires index values for fields ' '.
• 23505
• A secret named ' ' already exists.
• A secret named ' ' already exists.

AI-assisted analysis of elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/a414e121b21fb20d. Report an issue: GitHub.

Appendix: source

Thrown at src/modules/Elsa.Persistence.VNext/Document/DocumentIndexMatcher.cs:11

namespace Elsa.Persistence.VNext.Document;

public static class DocumentIndexMatcher
{
    public static DocumentIndex FindMatchingIndex(DocumentCollection collection, DocumentQuery query)
    {
        var filterFields = query.Filters.Keys.Order(StringComparer.Ordinal).ToArray();
        var index = collection.Indexes.SingleOrDefault(x => x.Fields.Order(StringComparer.Ordinal).SequenceEqual(filterFields, StringComparer.Ordinal));

        if (index is null)
            throw new DocumentQueryNotIndexedException(query.StorageUnit, filterFields);

        return index;
    }
}

View on GitHub (pinned to fe9217bdfa)