elsa-workflows/elsa-core · error · DocumentStoreValidationException

Document ID is required.

Error message

Document ID is required.

What it means

MongoDbDocumentStore.SaveAsync validates every save request before touching MongoDB. If the request's Id is null, empty, or whitespace it throws DocumentStoreValidationException, because the document's Id becomes the MongoDB _id key and cannot be defaulted. The library refuses to generate an Id on your behalf.

Solutions

  1. Assign a valid non-empty Id to SaveDocumentRequest.Id before calling SaveAsync (e.g. Guid.NewGuid().ToString()).
  2. Validate the request in your own layer before invoking the store so callers get a clear error about the missing Id.
  3. If Ids should be generated automatically, generate them at the source that builds SaveDocumentRequest; the store does not do this for you.

Example fix

// before
var request = new SaveDocumentRequest { Collection = "orders", IndexValues = indexValues };
await store.SaveAsync(collection, request, ct);

// after
var request = new SaveDocumentRequest { Id = Guid.NewGuid().ToString(), Collection = "orders", IndexValues = indexValues };
await store.SaveAsync(collection, request, ct);
Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(request.Id))
    throw new ArgumentException("Document ID must be set before saving.", nameof(request));

Type guard

static bool HasValidId(SaveDocumentRequest r) => !string.IsNullOrWhiteSpace(r.Id);

Try / catch

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

Prevention

When it happens

Trigger: Calling SaveAsync with a SaveDocumentRequest whose Id property is null, empty string, or whitespace-only — typically when a caller forgot to assign Id before saving a new document.

Common situations: Constructing SaveDocumentRequest from user input or an API payload where the client omitted the Id; deserializing a request model where Id wasn't mapped; generating documents in a loop where only the first had an assigned 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

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

Appendix: source

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

        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);
    }

    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)