{"record":{"id":"49b025b1a3e48d2d","repo":"elsa-workflows/elsa-core","slug":"runtime-entity-definition-document-document-id-could-not-be","errorCode":null,"errorMessage":"Runtime entity definition document '{document.Id}' could not be deserialized.","messagePattern":"Runtime entity definition document '(.+?)' could not be deserialized\\.","errorType":"validation","errorClass":"DocumentStoreValidationException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Persistence.VNext.Runtime/Services/RuntimeEntityManager.cs","lineNumber":232,"sourceCode":"            indexValues[$\"Index{slot}Value\"] = null;\n        }\n\n        for (var index = 0; index < definition.Indexes.Count; index++)\n        {\n            var indexedField = definition.Indexes[index].FieldName;\n            instance.Data.TryGetValue(indexedField, out var value);\n            var slot = index + 1;\n            indexValues[$\"Index{slot}Name\"] = indexedField;\n            indexValues[$\"Index{slot}Value\"] = ConvertIndexValue(value);\n        }\n\n        return indexValues;\n    }\n\n    private RuntimeEntityDefinition DeserializeDefinition(StoredDocument document)\n    {\n        return JsonSerializer.Deserialize<RuntimeEntityDefinition>(document.Content, _jsonOptions)\n            ?? throw new DocumentStoreValidationException($\"Runtime entity definition document '{document.Id}' could not be deserialized.\");\n    }\n\n    private RuntimeEntityInstance DeserializeInstance(StoredDocument document)\n    {\n        return JsonSerializer.Deserialize<RuntimeEntityInstance>(document.Content, _jsonOptions)\n            ?? throw new DocumentStoreValidationException($\"Runtime entity instance document '{document.Id}' could not be deserialized.\");\n    }\n\n    private RuntimeEntityAuditRecord DeserializeAudit(StoredDocument document)\n    {\n        return JsonSerializer.Deserialize<RuntimeEntityAuditRecord>(document.Content, _jsonOptions)\n            ?? throw new DocumentStoreValidationException($\"Runtime entity audit document '{document.Id}' could not be deserialized.\");\n    }\n\n    private static string NormalizeName(string name) => name.Trim().ToLowerInvariant();\n    private static string CreateInstanceDocumentId(string definitionName, string id) => $\"{NormalizeName(definitionName)}:{id}\";\n\n    private static string? ConvertIndexValue(object? value)","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Persistence.VNext.Runtime/Services/RuntimeEntityManager.cs#L214-L250","documentation":"DeserializeDefinition JSON-deserializes the StoredDocument.Content into RuntimeEntityDefinition using web defaults with a string enum converter. A null result (e.g. content is the JSON literal 'null' or an empty payload) throws DocumentStoreValidationException with the document id, indicating stored data the reader cannot turn into a definition.","triggerScenarios":"A stored definition document whose Content is null/empty/'null', was written by a different serializer configuration (e.g. numeric enums instead of string enums), or was corrupted/truncated externally.","commonSituations":"Manual database edits or migrations that wiped document content; switching serializer options between versions so old payloads no longer map; partial writes from a crashed process; reading documents written by another tool.","solutions":["Inspect the offending document's Content in the store and repair or delete/rewrite it via SaveDraftAsync.","Ensure documents are only written with matching JsonSerializerOptions (JsonSerializerDefaults.Web + JsonStringEnumConverter).","Restore the document from backup or re-provision the definition, then re-publish."],"exampleFix":"// before\nvar def = await manager.GetDefinitionAsync(\"orders\"); // throws on corrupt doc\n// after\ntry { var def = await manager.GetDefinitionAsync(\"orders\"); }\ncatch (DocumentStoreValidationException ex) {\n    logger.LogWarning(ex, \"Corrupt definition document; re-provisioning\");\n    await manager.SaveDraftAsync(RebuildDefinition(\"orders\"));\n}","handlingStrategy":"try-catch","validationCode":"var doc = /* load StoredDocument */;\nif (string.IsNullOrWhiteSpace(doc.Content) || doc.Content == \"null\")\n    throw new InvalidOperationException($\"Definition document '{doc.Id}' has empty content.\");","typeGuard":"bool IsValidDefinitionDocument(StoredDocument doc) =>\n    !string.IsNullOrWhiteSpace(doc.Content) && doc.Content != \"null\";","tryCatchPattern":"try { var def = await manager.GetDefinitionAsync(name); }\ncatch (DocumentStoreValidationException ex) { logger.LogError(ex, \"Corrupt definition document\"); /* repair or re-provision */ }","preventionTips":["Never edit stored document content manually.","Keep JsonSerializerOptions identical across all readers and writers and across versions.","Back up the document store before migrations."],"tags":["persistence","serialization","json","csharp"],"backgroundTag":"json-unmarshal-failed","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"}