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

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.

Solutions

1. Check that the storage-unit name string exactly matches (ordinal, case-sensitive) a collection declared in the persistence schema.
2. Ensure the schema/plan containing the collection is initialized before any Load/Delete call (run schema initialization at startup).
3. If the collection was renamed, update all call sites or add the old name as an alias in the plan.
4. Verify the DI-constructed RelationalDocumentStore is the one built from the correct configuration, not an empty default plan.

Example fix

// before
var doc = await store.LoadAsync("WorkflowInstnce", id, ...); // typo
// after
var doc = await store.LoadAsync("WorkflowInstances", id, ...); // matches declared collection

bool IsDeclared(RelationalDocumentStore plan, string unit) => plan.Collections.Any(c => string.Equals(c.Name, unit, StringComparison.Ordinal));
if (!IsDeclared(plan, unit)) throw new ArgumentException($"Unknown storage unit '{unit}'.");

try { await store.DeleteAsync(unit, id, ...); }
catch (DocumentStoreValidationException ex) { logger.LogWarning(ex, "Unknown storage unit {Unit}", unit); throw; }

When it happens

Trigger: Calling GetCollection via collection lookup, LoadAsync, or DeleteAsync with a storageUnit name that is not registered in _plan.Collections (exact ordinal match).

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Storage unit ' ' is not declared in the persistence schema.
• Document ID is required.
• Storage unit ' ' requires index values for fields ' '.
• Document ID is required.
• Storage unit ' ' requires index values for fields ' '.

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

Appendix: source

Thrown at src/modules/Elsa.Persistence.VNext.Relational/Documents/RelationalDocumentStore.cs:113

        await using var transaction = await _connection.BeginTransactionAsync(cancellationToken);
        var documentIds = await QueryDocumentIdsAsync(transaction, query, index, cancellationToken);
        var documents = new List<StoredDocument>();

        foreach (var documentId in documentIds)
        {
            var document = await LoadAsync(transaction, query.StorageUnit, documentId, cancellationToken);
            if (document is not null)
                documents.Add(document);
        }

        await transaction.CommitAsync(cancellationToken);
        return documents;
    }

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

    private static void ValidateSaveRequest(DocumentCollection collection, SaveDocumentRequest request)
    {
        if (string.IsNullOrWhiteSpace(request.Id))
            throw new DocumentStoreValidationException("Document ID is required.");

        var missingFields = collection.Indexes
            .SelectMany(x => x.Fields)
            .Distinct(StringComparer.Ordinal)
            .Where(field => !request.IndexValues.ContainsKey(field))
            .Order(StringComparer.Ordinal)
            .ToList();

        if (missingFields.Count > 0)
            throw new DocumentStoreValidationException($"Storage unit '{collection.Name}' requires index values for fields '{string.Join(", ", missingFields)}'.");
    }

View on GitHub (pinned to fe9217bdfa)