elsa-workflows/elsa-core · error · DocumentStoreValidationException

Storage unit ' ' is not declared in the persistence schema.

Error message

Storage unit '{storageUnit}' is not declared in the persistence schema.

What it means

MongoDbDocumentStore validates each query's storage unit against a precomputed collection plan built from the declared persistence schema. If the requested storage unit name does not match any declared collection, it throws DocumentStoreValidationException. This is a fail-fast guard against querying collections the MongoDb persistence module never declared/mapped.

Solutions

Register the missing storage unit/document mapping in the MongoDB persistence feature so the collection plan includes it.
Verify the exact storage unit name against the declared schema (case-sensitive Ordinal comparison).
Ensure the module that declares the document type is actually installed/configured in the host.
If a custom store, implement/extend the schema declaration API used by MongoDbDocumentStore to build _plan.Collections.

Example fix

// before
var docs = await store.QueryAsync(new Query { StorageUnit = "WorkflowInstance" }); // typo: unit not declared
// after
var docs = await store.QueryAsync(new Query { StorageUnit = "workflow-instances" }); // matches declared schema

Defensive patterns

Strategy: validation

Validate before calling

bool IsDeclared(MongoDbDocumentStore store, string storageUnit) =>
    store.GetDeclaredStorageUnits().Any(u => string.Equals(u, storageUnit, StringComparison.Ordinal));
if (!IsDeclared(store, "workflow-instances"))
    throw new InvalidOperationException("Storage unit not declared; register it in the MongoDB persistence feature.");

Try / catch

try
{
    var plan = store.Query(query);
}
catch (DocumentStoreValidationException ex)
{
    logger.LogError(ex, "Storage unit not declared in Mongo persistence schema");
    throw; // configuration bug — do not swallow
}

Prevention

Centralize storage unit name constants instead of passing raw strings.
Register any custom document/collection mappings with the MongoDB persistence feature at startup.
Add a startup smoke test that resolves every storage unit your app queries.
Watch for case mismatches — the comparison is Ordinal (case-sensitive).

When it happens

Trigger: Calling store/query APIs (via collectionPlan -> GetCollectionPlan) with a storage unit name that isn't registered in the MongoDB persistence schema — e.g. an activity/entity type not mapped, a typo'd storage unit name, or a module's document type missing from the configured persistence feature.

Common situations: Adding a custom entity/document store without registering it in the MongoDB persistence feature; renaming a collection in schema without updating callers; version drift where a newer module expects a storage unit an older schema doesn't declare; typos when querying by string name.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/modules/Elsa.Persistence.VNext.MongoDb/MongoDbDocumentStore.cs:128

        var collectionPlan = GetCollectionPlan(query.StorageUnit);
        _ = DocumentIndexMatcher.FindMatchingIndex(collectionPlan.Collection, query);
        var filters = query.Filters
            .OrderBy(x => x.Key, StringComparer.Ordinal)
            .Select(filter => Builders<BsonDocument>.Filter.Eq($"IndexValues.{filter.Key}", filter.Value is null ? BsonNull.Value : BsonValue.Create(filter.Value)))
            .ToList();
        var mongoFilter = Builders<BsonDocument>.Filter.And(filters);
        var documents = await GetMongoCollection(collectionPlan)
            .Find(mongoFilter)
            .Sort(Builders<BsonDocument>.Sort.Ascending("_id"))
            .ToListAsync(cancellationToken);

        return documents.Select(document => ReadDocument(document, query.StorageUnit)).ToList();
    }

    private MongoDbCollectionPlan GetCollectionPlan(string storageUnit)
    {
        return _plan.Collections.SingleOrDefault(x => string.Equals(x.Collection.Name, storageUnit, StringComparison.Ordinal))
            ?? throw new DocumentStoreValidationException($"Storage unit '{storageUnit}' is not declared in the persistence schema.");
    }

    private IMongoCollection<BsonDocument> GetMongoCollection(MongoDbCollectionPlan collectionPlan)
    {
        return _database.GetCollection<BsonDocument>(collectionPlan.CollectionName);
    }

    private async Task EnsureCollectionExistsAsync(string collectionName, CancellationToken cancellationToken)
    {
        using var cursor = await _database.ListCollectionNamesAsync(new ListCollectionNamesOptions
        {
            Filter = new BsonDocument("name", collectionName)
        }, cancellationToken);

        var exists = await cursor.MoveNextAsync(cancellationToken) && cursor.Current.Any();
        if (!exists)
            await _database.CreateCollectionAsync(collectionName, cancellationToken: cancellationToken);
    }

View on GitHub (pinned to fe9217bdfa)