{"record":{"id":"0109a545fb3755e5","repo":"elsa-workflows/elsa-core","slug":"storage-unit-storageunit-is-not-declared-in-the-persistence-0109a5","errorCode":null,"errorMessage":"Storage unit '{storageUnit}' is not declared in the persistence schema.","messagePattern":"Storage unit '(.+?)' is not declared in the persistence schema\\.","errorType":"validation","errorClass":"DocumentStoreValidationException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Persistence.VNext.Relational/Documents/RelationalDocumentStore.cs","lineNumber":113,"sourceCode":"        await using var transaction = await _connection.BeginTransactionAsync(cancellationToken);\n        var documentIds = await QueryDocumentIdsAsync(transaction, query, index, cancellationToken);\n        var documents = new List<StoredDocument>();\n\n        foreach (var documentId in documentIds)\n        {\n            var document = await LoadAsync(transaction, query.StorageUnit, documentId, cancellationToken);\n            if (document is not null)\n                documents.Add(document);\n        }\n\n        await transaction.CommitAsync(cancellationToken);\n        return documents;\n    }\n\n    private DocumentCollection GetCollection(string storageUnit)\n    {\n        return _plan.Collections.SingleOrDefault(x => string.Equals(x.Name, storageUnit, StringComparison.Ordinal))\n            ?? throw new DocumentStoreValidationException($\"Storage unit '{storageUnit}' is not declared in the persistence schema.\");\n    }\n\n    private static void ValidateSaveRequest(DocumentCollection collection, SaveDocumentRequest request)\n    {\n        if (string.IsNullOrWhiteSpace(request.Id))\n            throw new DocumentStoreValidationException(\"Document ID is required.\");\n\n        var missingFields = collection.Indexes\n            .SelectMany(x => x.Fields)\n            .Distinct(StringComparer.Ordinal)\n            .Where(field => !request.IndexValues.ContainsKey(field))\n            .Order(StringComparer.Ordinal)\n            .ToList();\n\n        if (missingFields.Count > 0)\n            throw new DocumentStoreValidationException($\"Storage unit '{collection.Name}' requires index values for fields '{string.Join(\", \", missingFields)}'.\");\n    }\n","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Persistence.VNext.Relational/Documents/RelationalDocumentStore.cs#L95-L131","documentation":"RelationalDocumentStore keeps an in-memory schema plan of declared collections ('storage units'). Any operation against a storage unit not present in the plan fails fast with DocumentStoreValidationException. This guards against typos and against using the store before its schema was initialized.","triggerScenarios":"Calling GetCollection via collection lookup, LoadAsync, or DeleteAsync with a storageUnit name that is not registered in _plan.Collections (exact ordinal match).","commonSituations":"Typo or casing mismatch in the storage-unit name; referencing a collection before schema initialization/registration ran; schema plan rebuilt after a definition was removed; multi-tenant code passing the wrong unit name.","solutions":["Check that the storage-unit name string exactly matches (ordinal, case-sensitive) a collection declared in the persistence schema.","Ensure the schema/plan containing the collection is initialized before any Load/Delete call (run schema initialization at startup).","If the collection was renamed, update all call sites or add the old name as an alias in the plan.","Verify the DI-constructed RelationalDocumentStore is the one built from the correct configuration, not an empty default plan."],"exampleFix":"// before\nvar doc = await store.LoadAsync(\"WorkflowInstnce\", id, ...); // typo\n// after\nvar doc = await store.LoadAsync(\"WorkflowInstances\", id, ...); // matches declared collection","handlingStrategy":"validation","validationCode":"bool IsDeclared(RelationalDocumentStore plan, string unit) => plan.Collections.Any(c => string.Equals(c.Name, unit, StringComparison.Ordinal));\nif (!IsDeclared(plan, unit)) throw new ArgumentException($\"Unknown storage unit '{unit}'.\");","typeGuard":null,"tryCatchPattern":"try { await store.DeleteAsync(unit, id, ...); }\ncatch (DocumentStoreValidationException ex) { logger.LogWarning(ex, \"Unknown storage unit {Unit}\", unit); throw; }","preventionTips":["Centralize storage-unit names as constants, never inline strings.","Run schema initialization at startup and fail fast if a referenced unit is missing.","Use an enum or strongly-typed wrapper for unit names."],"tags":["persistence","validation","relational"],"backgroundTag":"resource-not-found","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"}