{"record":{"id":"6529707c74a26f6b","repo":"elsa-workflows/elsa-core","slug":"runtime-entity-instance-document-document-id-could-not-be","errorCode":null,"errorMessage":"Runtime entity instance document '{document.Id}' could not be deserialized.","messagePattern":"Runtime entity instance document '(.+?)' could not be deserialized\\.","errorType":"validation","errorClass":"DocumentStoreValidationException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Persistence.VNext.Runtime/Services/RuntimeEntityManager.cs","lineNumber":238,"sourceCode":"            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)\n    {\n        return value switch\n        {\n            null => null,\n            DateTimeOffset dateTimeOffset => dateTimeOffset.ToString(\"O\", CultureInfo.InvariantCulture),\n            DateTime dateTime => dateTime.ToUniversalTime().ToString(\"O\", CultureInfo.InvariantCulture),","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Persistence.VNext.Runtime/Services/RuntimeEntityManager.cs#L220-L256","documentation":"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.","triggerScenarios":"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.","commonSituations":"Serializer option drift between service versions; manual DB fixes; partial writes after crashes; importing documents serialized with PascalCase or without the string-enum converter.","solutions":["Inspect and repair or remove the corrupt instance document, then rewrite it via SaveInstanceAsync.","Write all documents with the same JsonSerializerOptions used for reads (Web defaults + JsonStringEnumConverter).","Restore from backup or re-create the affected instances."],"exampleFix":"// before\nvar inst = await manager.GetInstanceAsync(\"orders\", id); // throws on corrupt doc\n// after\nRuntimeEntityInstance? inst = null;\ntry { inst = await manager.GetInstanceAsync(\"orders\", id); }\ncatch (DocumentStoreValidationException ex) {\n    logger.LogWarning(ex, \"Corrupt instance {Id}; recreating\", id);\n    inst = await manager.SaveInstanceAsync(RebuildInstance(\"orders\", id));\n}","handlingStrategy":"try-catch","validationCode":"var doc = /* load StoredDocument */;\nif (string.IsNullOrWhiteSpace(doc.Content) || doc.Content == \"null\")\n    throw new InvalidOperationException($\"Instance document '{doc.Id}' has empty content.\");","typeGuard":"bool IsValidInstanceDocument(StoredDocument doc) =>\n    !string.IsNullOrWhiteSpace(doc.Content) && doc.Content != \"null\";","tryCatchPattern":"try { var inst = await manager.GetInstanceAsync(defName, id); }\ncatch (DocumentStoreValidationException ex) { logger.LogError(ex, \"Corrupt instance document {Id}\", id); }","preventionTips":["Use the manager's SaveInstanceAsync for all writes so serialization options stay consistent.","Avoid mixed package versions that could change JSON naming or enum handling.","Monitor for DocumentStoreValidationException as a data-corruption signal."],"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-15T23:17:13.987Z"}