{"record":{"id":"95ddf5c0dc2dd8c7","repo":"microsoft/semantic-kernel","slug":"failed-to-deserialize-schema","errorCode":null,"errorMessage":"Failed to deserialize schema.","messagePattern":"Failed to deserialize schema\\.","errorType":"exception","errorClass":"KernelException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Experimental/Process.Core/Workflow/WorkflowBuilder.cs","lineNumber":371,"sourceCode":"                if (property.PropertyType == typeof(List<ChatMessageContent>))\n                {\n                    workflow.Variables.Add(property.Name, new VariableDefinition()\n                    {\n                        Type = VariableType.Messages,\n                    });\n\n                    continue;\n                }\n\n                var schema = KernelJsonSchemaBuilder.Build(property.PropertyType);\n                var schemaJson = JsonSerializer.Serialize(schema.RootElement);\n\n                var deserializer = new DeserializerBuilder()\n                .WithNamingConvention(UnderscoredNamingConvention.Instance)\n                .IgnoreUnmatchedProperties()\n                .Build();\n\n                var yamlSchema = deserializer.Deserialize(schemaJson) ?? throw new KernelException(\"Failed to deserialize schema.\");\n                workflow.Variables.Add(property.Name, new VariableDefinition { Type = VariableType.UserDefined, Schema = yamlSchema });\n            }\n        }\n\n        // Add edges\n        var orchestration = new List<OrchestrationStep>();\n        foreach (var edge in process.Edges)\n        {\n            // Get all the input events\n            OrchestrationStep orchestrationStep = new()\n            {\n                ListenFor = new ListenCondition()\n                {\n                    From = \"_workflow_\",\n                    Event = ResolveEventName(edge.Key)\n                },\n                Then = [.. edge.Value.Select(e => ThenAction.FromKernelProcessEdge(e, null))]\n            };","sourceCodeStart":353,"sourceCodeEnd":389,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Experimental/Process.Core/Workflow/WorkflowBuilder.cs#L353-L389","documentation":"Thrown during `BuildWorkflow` when converting a `UserStateType` property's JSON schema to a YAML schema object via YamlDotNet returns null. The library builds a JSON schema with `KernelJsonSchemaBuilder`, serializes it to a JSON string, and deserializes that string as YAML; a null result means the schema content could not be parsed into an object graph. It is a KernelException raised in the user-state-variable loop.","triggerScenarios":"Declare a process `UserStateType` whose public property produces a JSON schema string that YamlDotNet deserializes to null (e.g. an effectively empty or malformed schema root element); a property type that `KernelJsonSchemaBuilder.Build` returns an empty/rootless schema for.","commonSituations":"Adding a complex or generic user-state property whose schema generation yields no usable root element; mismatches between the JSON schema builder version and the expected schema shape; using unsupported property types.","solutions":["Inspect the generated JSON schema for the offending property by calling `KernelJsonSchemaBuilder.Build(prop.PropertyType)` directly and serializing it; confirm it is non-empty.","Simplify or annotate the offending property type so schema generation produces a valid root element.","If a property cannot be schema-fied, exclude it from UserStateType or wrap it in a type with a known schema."],"exampleFix":"// before\npublic class MyUserState { public ComplexUnmappedType Weird { get; set; } }\n// after (replace with a schema-serializable type)\npublic class MyUserState { public string Note { get; set; } }","handlingStrategy":"try-catch","validationCode":"foreach (var property in process.UserStateType?.GetProperties() ?? Array.Empty<PropertyInfo>())\n{\n    if (property.PropertyType == typeof(List<ChatMessageContent>)) continue;\n    var schema = KernelJsonSchemaBuilder.Build(property.PropertyType);\n    var schemaJson = JsonSerializer.Serialize(schema.RootElement);\n    if (string.IsNullOrWhiteSpace(schemaJson) || schemaJson == \"null\")\n        throw new InvalidOperationException($\"UserState property '{property.Name}' yields an empty schema.\");\n}","typeGuard":"bool HasNonEmptySchema(Type t)\n{\n    var s = KernelJsonSchemaBuilder.Build(t);\n    var json = JsonSerializer.Serialize(s.RootElement);\n    return !string.IsNullOrWhiteSpace(json) && json != \"null\";\n}","tryCatchPattern":"try { await WorkflowBuilder.BuildWorkflow(process); }\ncatch (KernelException ex) when (ex.Message.Contains(\"Failed to deserialize schema\"))\n{ _logger.LogError(ex, \"A UserState property produced an un-deserializable schema; simplify its type.\"); throw; }","preventionTips":["Keep UserStateType properties to simple, schema-serializable CLR types.","Unit-test schema generation for each UserStateType at design time.","Avoid open generics or types without public parameterless constructors."],"tags":["workflow","process-framework","serialization","schema","yaml"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}