elsa-workflows/elsa-core · error · DocumentStoreValidationException

Runtime entity instance document

Error message

Runtime entity instance document '{document.Id}' could not be deserialized.

What it means

DeserializeInstance JSON-deserializes StoredDocument.Content into RuntimeEntityInstance. If deserialization yields null (content empty, 'null', or written with incompatible serializer settings) it throws DocumentStoreValidationException including the document id. Called by LoadInstanceDocumentAsync, so GetInstanceAsync and SaveInstanceAsync read-paths can surface it.

Solutions

1. Inspect and repair or remove the corrupt instance document, then rewrite it via SaveInstanceAsync.
2. Write all documents with the same JsonSerializerOptions used for reads (Web defaults + JsonStringEnumConverter).
3. Restore from backup or re-create the affected instances.

Example fix

// before
var inst = await manager.GetInstanceAsync("orders", id); // throws on corrupt doc
// after
RuntimeEntityInstance? inst = null;
try { inst = await manager.GetInstanceAsync("orders", id); }
catch (DocumentStoreValidationException ex) {
    logger.LogWarning(ex, "Corrupt instance {Id}; recreating", id);
    inst = await manager.SaveInstanceAsync(RebuildInstance("orders", id));
}

var doc = /* load StoredDocument */;
if (string.IsNullOrWhiteSpace(doc.Content) || doc.Content == "null")
    throw new InvalidOperationException($"Instance document '{doc.Id}' has empty content.");

bool IsValidInstanceDocument(StoredDocument doc) =>
    !string.IsNullOrWhiteSpace(doc.Content) && doc.Content != "null";

try { var inst = await manager.GetInstanceAsync(defName, id); }
catch (DocumentStoreValidationException ex) { logger.LogError(ex, "Corrupt instance document {Id}", id); }

When it happens

Trigger: An instance document stored with null/empty/'null' Content, written by code using different JSON options (e.g. numeric enums or different casing policy), or corrupted by external edits/migrations.

Common situations: Serializer option drift between service versions; manual DB fixes; partial writes after crashes; importing documents serialized with PascalCase or without the string-enum converter.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Runtime entity definition document
• The persisted external authentication value could not be…
• Runtime entity audit document
• Failed to parse JsonDocument
• Failed to extract activity type property

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

Appendix: source

Thrown at src/modules/Elsa.Persistence.VNext.Runtime/Services/RuntimeEntityManager.cs:238

            instance.Data.TryGetValue(indexedField, out var value);
            var slot = index + 1;
            indexValues[$"Index{slot}Name"] = indexedField;
            indexValues[$"Index{slot}Value"] = ConvertIndexValue(value);
        }

        return indexValues;
    }

    private RuntimeEntityDefinition DeserializeDefinition(StoredDocument document)
    {
        return JsonSerializer.Deserialize<RuntimeEntityDefinition>(document.Content, _jsonOptions)
            ?? throw new DocumentStoreValidationException($"Runtime entity definition document '{document.Id}' could not be deserialized.");
    }

    private RuntimeEntityInstance DeserializeInstance(StoredDocument document)
    {
        return JsonSerializer.Deserialize<RuntimeEntityInstance>(document.Content, _jsonOptions)
            ?? throw new DocumentStoreValidationException($"Runtime entity instance document '{document.Id}' could not be deserialized.");
    }

    private RuntimeEntityAuditRecord DeserializeAudit(StoredDocument document)
    {
        return JsonSerializer.Deserialize<RuntimeEntityAuditRecord>(document.Content, _jsonOptions)
            ?? throw new DocumentStoreValidationException($"Runtime entity audit document '{document.Id}' could not be deserialized.");
    }

    private static string NormalizeName(string name) => name.Trim().ToLowerInvariant();
    private static string CreateInstanceDocumentId(string definitionName, string id) => $"{NormalizeName(definitionName)}:{id}";

    private static string? ConvertIndexValue(object? value)
    {
        return value switch
        {
            null => null,
            DateTimeOffset dateTimeOffset => dateTimeOffset.ToString("O", CultureInfo.InvariantCulture),
            DateTime dateTime => dateTime.ToUniversalTime().ToString("O", CultureInfo.InvariantCulture),

View on GitHub (pinned to fe9217bdfa)