elsa-workflows/elsa-core · error · DocumentStoreValidationException

Document ID is required.

Error message

Document ID is required.

What it means

SaveAsync validates each save request before writing. A document with a null, empty, or whitespace-only Id cannot be identified or keyed in the store, so SaveAsync throws DocumentStoreValidationException. The Id is the primary identity used for upserts and versioning.

Solutions

1. Populate SaveDocumentRequest.Id before calling SaveAsync.
2. If the entity is new, generate an identifier (Guid.NewGuid().ToString("N") or your ID generator) prior to saving.
3. Check upstream mapping code that constructs the request to ensure the source object's ID is not lost during mapping.

Example fix

// before
await store.SaveAsync(collection, new SaveDocumentRequest { Data = doc });
// after
await store.SaveAsync(collection, new SaveDocumentRequest { Id = doc.Id ?? Guid.NewGuid().ToString("N"), Data = doc });

if (string.IsNullOrWhiteSpace(request.Id)) throw new InvalidOperationException("Cannot save document without an Id.");

try { await store.SaveAsync(collection, request); }
catch (DocumentStoreValidationException ex) { logger.LogError(ex, "Invalid save request"); throw; }

When it happens

Trigger: Calling SaveAsync with a SaveDocumentRequest whose Id property is null, empty string, or whitespace.

Common situations: Building the request dynamically and forgetting to assign the Id; a domain object whose identifier field was never populated (e.g. new entity that should have gotten an ID from a generator); deserialization produced a default/empty ID.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — 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 ' '.
• Storage unit ' ' is not declared in the persistence schema.
• Storage unit ' ' requires index values for fields ' '.

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

Appendix: source

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

            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)}'.");
    }

    private static void ValidateExpectedVersion(string storageUnit, string documentId, long? expectedVersion, long? actualVersion)
    {
        if (expectedVersion is null)
            return;

        if (expectedVersion != (actualVersion ?? 0))

View on GitHub (pinned to fe9217bdfa)