{"record":{"id":"09e21cffeb750463","repo":"microsoft/semantic-kernel","slug":"the-initial-state-provided-for-step-this-name-is","errorCode":null,"errorMessage":"The initial state provided for step {this.Name} is not of the correct type. The expected type is {userStateType.Name}.","messagePattern":"The initial state provided for step (.+?) is not of the correct type\\. The expected type is (.+?)\\.","errorType":"exception","errorClass":"KernelException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Experimental/Process.Core/ProcessStepBuilder.cs","lineNumber":318,"sourceCode":"        if (this._stepType.TryGetSubtypeOfStatefulStep(out Type? genericStepType) && genericStepType is not null)\n        {\n            // The step is a subclass of KernelProcessStep<>, so we need to extract the generic type argument\n            // and create an instance of the corresponding KernelProcessStepState<>.\n            var userStateType = genericStepType.GetGenericArguments()[0];\n            Verify.NotNull(userStateType);\n\n            var stateType = typeof(KernelProcessStepState<>).MakeGenericType(userStateType);\n            Verify.NotNull(stateType);\n\n            if (stateMetadata != null && stateMetadata.State != null && stateMetadata.State is JsonElement jsonState)\n            {\n                try\n                {\n                    this._initialState = jsonState.Deserialize(userStateType);\n                }\n                catch (JsonException)\n                {\n                    throw new KernelException($\"The initial state provided for step {this.Name} is not of the correct type. The expected type is {userStateType.Name}.\");\n                }\n            }\n\n            // If the step has a user-defined state then we need to validate that the initial state is of the correct type.\n            if (this._initialState is not null && this._initialState.GetType() != userStateType)\n            {\n                throw new KernelException($\"The initial state provided for step {this.Name} is not of the correct type. The expected type is {userStateType.Name}.\");\n            }\n\n            var initialState = this._initialState ?? Activator.CreateInstance(userStateType);\n            stateObject = (KernelProcessStepState?)Activator.CreateInstance(stateType, this.Name, stepMetadataAttributes.Version, this.Id);\n            stateType.GetProperty(nameof(KernelProcessStepState<object>.State))?.SetValue(stateObject, initialState);\n        }\n        else\n        {\n            // The step is a KernelProcessStep with no user-defined state, so we can use the base KernelProcessStepState.\n            stateObject = new KernelProcessStepState(this.Name, stepMetadataAttributes.Version, this.Id);\n        }","sourceCodeStart":300,"sourceCodeEnd":336,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Experimental/Process.Core/ProcessStepBuilder.cs#L300-L336","documentation":"Thrown by ProcessStepBuilder.BuildStep during JSON deserialization of a stateful step's initial state. The step derives from KernelProcessStep<TState>, and the state metadata supplied at build time is a JsonElement that cannot be deserialized into the user-defined state type TState. The framework catches the inner JsonException and rethrows this KernelException to surface a clear, type-named failure.","triggerScenarios":"Calling Build() on a ProcessBuilder whose stateful step was given KernelProcessStepStateMetadata with a State JsonElement whose shape does not match the declared user state type (missing properties, wrong property types, malformed JSON, or a state payload belonging to a different step type).","commonSituations":"Loading a process from serialized state where the schema evolved (renamed/removed TState fields), pasting state JSON from another step, or supplying a JsonElement produced by a different JsonSerializerOptions that yields incompatible tokens.","solutions":["Inspect the expected type named in the message and reconcile your state JSON so every property matches the TState POCO (names, types, nullability).","Deserialize the same JsonElement with JsonSerializer.Deserialize<TState>(jsonState) in a scratch test to capture the real JsonException with line/byte/path detail.","Ensure the JsonSerializerOptions used to produce the JsonElement (e.g. property naming policy, case sensitivity) match what TState expects.","If the state legitimately belongs to a different step, route it to the correct step or update the step's generic state argument."],"exampleFix":"// before: state JSON has { \"count\": 5 } but TState expects an int named \"Counter\"\nstepBuilder.BuildStep(pb, stateMetadata);\n\n// after: align JSON property name to TState\n// { \"Counter\": 5 }\nstepBuilder.BuildStep(pb, stateMetadata);","handlingStrategy":"validation","validationCode":"// Validate the state JsonElement round-trips into TState before building\nbool CanDeserializeState<TState>(JsonElement el, JsonSerializerOptions opt)\n{\n    try { el.Deserialize<TState>(opt); return true; }\n    catch (JsonException) { return false; }\n}","typeGuard":"bool IsStateForStep<TState>(object state) => state is JsonElement el && CanDeserializeState<TState>(el, JsonSerializerOptions.Default);","tryCatchPattern":"try { builder.Build(); }\ncatch (KernelException ex) when (ex.Message.Contains(\"is not of the correct type\"))\n{\n    // log expectedType, re-serialize the supplied JsonElement for comparison\n}","preventionTips":["Keep a single source of truth for TState schema and generate JSON from it.","Add a unit test that round-trips each step's sample state JSON through Deserialize<TState>.","Version state types and migrate serialized state when fields change."],"tags":["semantic-kernel","process","serialization","state","json"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}