microsoft/semantic-kernel · error · KernelException

Type '{stepStateType.Value}' is not a valid KernelProcessSte

Error message

Type '{stepStateType.Value}' is not a valid KernelProcessStepState type.

What it means

After resolving the persisted state type via Type.GetType, ActivateStepAsync validates that it inherits from KernelProcessStepState. If it does not, this KernelException is thrown. Only KernelProcessStepState-derived types (including KernelProcessStepState<TState>) can be used as step state.

Source

Thrown at dotnet/src/Experimental/Process.Runtime.Dapr/Actors/StepActor.cs:388

        this._inputs = this._initialInputs.ToDictionary(kvp => kvp.Key, kvp => kvp.Value?.ToDictionary(kvp => kvp.Key, kvp => kvp.Value));

        // Activate the step with user-defined state if needed
        KernelProcessStepState? stateObject = null;
        Type? stateType = null;

        // Check if the state has already been persisted
        var stepStateType = await this.StateManager.TryGetStateAsync<string>(ActorStateKeys.StepStateType).ConfigureAwait(false);
        if (stepStateType.HasValue)
        {
            stateType = Type.GetType(stepStateType.Value);
            if (stateType is null)
            {
                throw new KernelException($"Type '{stepStateType.Value}' could not be resolved to a valid KernelProcessStepState type.").Log(this._logger);
            }

            if (!typeof(KernelProcessStepState).IsAssignableFrom(stateType))
            {
                throw new KernelException($"Type '{stepStateType.Value}' is not a valid KernelProcessStepState type.").Log(this._logger);
            }

            var stateObjectJson = await this.StateManager.GetStateAsync<string>(ActorStateKeys.StepStateJson).ConfigureAwait(false);
            stateObject = JsonSerializer.Deserialize(stateObjectJson, stateType) as KernelProcessStepState;
        }
        else
        {
            stateType = this._innerStepType.ExtractStateType(out Type? userStateType, this._logger);
            stateObject = this._stepInfo.State;

            // Persist the state type and type object.
            await this.StateManager.AddStateAsync(ActorStateKeys.StepStateType, stateType.AssemblyQualifiedName).ConfigureAwait(false);
            await this.StateManager.AddStateAsync(ActorStateKeys.StepStateJson, JsonSerializer.Serialize(stateObject)).ConfigureAwait(false);
            await this.StateManager.SaveStateAsync().ConfigureAwait(false);
        }

        if (stateType is null || stateObject is null)
        {

View on GitHub (pinned to c028a0c7dc)

Solutions

Clear the persisted StepStateType and StepStateJson from the Dapr state store so the actor re-derives the correct state type from the step type.
If the state type legitimately changed, ensure the new type still inherits from KernelProcessStepState.
Audit the Dapr state store to confirm StepStateType contains a valid KernelProcessStepState-derived type name.

Defensive patterns

Strategy: validation

Validate before calling

// Validate persisted state type before activation:
var stepStateType = await stateManager.TryGetStateAsync<string>(ActorStateKeys.StepStateType);
if (stepStateType.HasValue)
{
    Type? t = Type.GetType(stepStateType.Value);
    if (t is not null && !typeof(KernelProcessStepState).IsAssignableFrom(t))
    {
        logger.LogWarning("Persisted state type '{Type}' is not a KernelProcessStepState. Clearing state.", stepStateType.Value);
        // Clear persisted state to allow re-derivation
    }
}

Type guard

static bool IsValidStateType(string assemblyQualifiedName)
{
    var t = Type.GetType(assemblyQualifiedName);
    return t is not null && typeof(KernelProcessStepState).IsAssignableFrom(t);
}

Try / catch

try
{
    await stepActor.PrepareIncomingMessagesAsync();
}
catch (KernelException ex) when (ex.Message.Contains("not a valid KernelProcessStepState type"))
{
    logger.LogError("Persisted state type is invalid. Clear Dapr state store entries for this actor.");
}

Prevention

Do not manually edit or corrupt persisted StepStateType values in the Dapr state store.
Ensure state type migrations preserve KernelProcessStepState inheritance.
Clear persisted state when the state type hierarchy changes.

When it happens

Trigger: The persisted StepStateType resolves to a CLR type, but that type is not assignable to KernelProcessStepState. This indicates the persisted state was corrupted, manually tampered with, or a non-state type name was persisted.

Common situations: Corrupted Dapr state store entries where StepStateType holds a non-state type name. A custom serialization issue that wrote the wrong type name. A migration that replaced the state type with an incompatible type that no longer inherits from KernelProcessStepState.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/ac2112e66ceefb4e. Report an issue: GitHub.