{"record":{"id":"da89a7a03e8be347","repo":"elsa-workflows/elsa-core","slug":"storage-unit-storageunit-is-not-declared-in-the-persistence","errorCode":null,"errorMessage":"Storage unit '{storageUnit}' is not declared in the persistence schema.","messagePattern":"Storage unit '(.+?)' is not declared in the persistence schema\\.","errorType":"exception","errorClass":"DocumentStoreValidationException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Persistence.VNext.MongoDb/MongoDbDocumentStore.cs","lineNumber":128,"sourceCode":"        var collectionPlan = GetCollectionPlan(query.StorageUnit);\n        _ = DocumentIndexMatcher.FindMatchingIndex(collectionPlan.Collection, query);\n        var filters = query.Filters\n            .OrderBy(x => x.Key, StringComparer.Ordinal)\n            .Select(filter => Builders<BsonDocument>.Filter.Eq($\"IndexValues.{filter.Key}\", filter.Value is null ? BsonNull.Value : BsonValue.Create(filter.Value)))\n            .ToList();\n        var mongoFilter = Builders<BsonDocument>.Filter.And(filters);\n        var documents = await GetMongoCollection(collectionPlan)\n            .Find(mongoFilter)\n            .Sort(Builders<BsonDocument>.Sort.Ascending(\"_id\"))\n            .ToListAsync(cancellationToken);\n\n        return documents.Select(document => ReadDocument(document, query.StorageUnit)).ToList();\n    }\n\n    private MongoDbCollectionPlan GetCollectionPlan(string storageUnit)\n    {\n        return _plan.Collections.SingleOrDefault(x => string.Equals(x.Collection.Name, storageUnit, StringComparison.Ordinal))\n            ?? throw new DocumentStoreValidationException($\"Storage unit '{storageUnit}' is not declared in the persistence schema.\");\n    }\n\n    private IMongoCollection<BsonDocument> GetMongoCollection(MongoDbCollectionPlan collectionPlan)\n    {\n        return _database.GetCollection<BsonDocument>(collectionPlan.CollectionName);\n    }\n\n    private async Task EnsureCollectionExistsAsync(string collectionName, CancellationToken cancellationToken)\n    {\n        using var cursor = await _database.ListCollectionNamesAsync(new ListCollectionNamesOptions\n        {\n            Filter = new BsonDocument(\"name\", collectionName)\n        }, cancellationToken);\n\n        var exists = await cursor.MoveNextAsync(cancellationToken) && cursor.Current.Any();\n        if (!exists)\n            await _database.CreateCollectionAsync(collectionName, cancellationToken: cancellationToken);\n    }","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Persistence.VNext.MongoDb/MongoDbDocumentStore.cs#L110-L146","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nvar docs = await store.QueryAsync(new Query { StorageUnit = \"WorkflowInstance\" }); // typo: unit not declared\n// after\nvar docs = await store.QueryAsync(new Query { StorageUnit = \"workflow-instances\" }); // matches declared schema","handlingStrategy":"validation","validationCode":"bool IsDeclared(MongoDbDocumentStore store, string storageUnit) =>\n    store.GetDeclaredStorageUnits().Any(u => string.Equals(u, storageUnit, StringComparison.Ordinal));\nif (!IsDeclared(store, \"workflow-instances\"))\n    throw new InvalidOperationException(\"Storage unit not declared; register it in the MongoDB persistence feature.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    var plan = store.Query(query);\n}\ncatch (DocumentStoreValidationException ex)\n{\n    logger.LogError(ex, \"Storage unit not declared in Mongo persistence schema\");\n    throw; // configuration bug — do not swallow\n}","preventionTips":["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)."],"tags":["mongodb","persistence","schema","validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"fe9217bdfa0e27f0e09e45006eb6898f616e513d","analyzedAt":"2026-09-13T20:32:34.702Z","contentChangedAt":"2026-09-13T20:32:34.702Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}