What causes "Failed to deserialize the process string." in microsoft/semantic-kernel?

Inspect the InnerException of the thrown ArgumentException for the real cause (e.g. YamlDotNet parse error, type-not-found, etc.).

microsoft/semantic-kernel · error · ArgumentException

Failed to deserialize the process string.

Error message

Failed to deserialize the process string.

What it means

Thrown by ProcessBuilder.LoadFromYamlInternalAsync as a catch-all wrapper around any exception that occurs during YAML deserialization or process building. The original exception is preserved as the InnerException. The message is generic, so inspecting InnerException is essential for root-cause diagnosis.

Source

Thrown at dotnet/src/Experimental/Process.Core/ProcessBuilder.cs:595

        {
            var workflow = WorkflowSerializer.DeserializeFromYaml(yaml);
            var builder = new WorkflowBuilder();

            if (stepTypes is not null)
            {
                return await builder.BuildProcessAsync(workflow, yaml, stepTypes).ConfigureAwait(false);
            }
            else if (assemblyPaths is { Count: > 0 })
            {
                var loadedStepTypes = ProcessStepLoader.LoadStepTypesFromAssemblies(assemblyPaths);
                return await builder.BuildProcessAsync(workflow, yaml, loadedStepTypes).ConfigureAwait(false);
            }

            return await builder.BuildProcessAsync(workflow, yaml).ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            throw new ArgumentException("Failed to deserialize the process string.", ex);
        }
    }
    #endregion
}

View on GitHub (pinned to c028a0c7dc)

Solutions

Inspect the InnerException of the thrown ArgumentException for the real cause (e.g. YamlDotNet parse error, type-not-found, etc.).
Validate the YAML string with a YAML linter before calling LoadFromYamlAsync.
If using step type names in YAML, ensure you pass the correct stepTypes dictionary or assemblyPaths so all referenced types are resolvable.
Temporarily call WorkflowSerializer.DeserializeFromYaml directly to isolate parsing errors from build errors.

Example fix

// before
try
{
    var process = await ProcessBuilder.LoadFromYamlAsync(yaml);
}
catch (ArgumentException ex)
{
    // ex.Message is generic; root cause is hidden
}

// after — unwrap InnerException for diagnostics
try
{
    var process = await ProcessBuilder.LoadFromYamlAsync(yaml);
}
catch (ArgumentException ex) when (ex.InnerException is not null)
{
    Console.WriteLine($"Root cause: {ex.InnerException.GetType().Name}: {ex.InnerException.Message}");
}

Defensive patterns

Strategy: try-catch

Validate before calling

try
{
    var workflow = WorkflowSerializer.DeserializeFromYaml(yaml);
}
catch (Exception ex)
{
    throw new InvalidOperationException("YAML parsing failed before process load. See inner exception.", ex);
}

var process = await ProcessBuilder.LoadFromYamlAsync(yaml);

Try / catch

try
{
    var process = await ProcessBuilder.LoadFromYamlAsync(yaml, stepTypes);
}
catch (ArgumentException ex) when (ex.InnerException is not null)
{
    logger.LogError(ex.InnerException, "Process YAML load failed: {Message}", ex.InnerException.Message);
    throw;
}

Prevention

Always inspect InnerException when catching this ArgumentException — the outer message is generic.
Validate YAML syntax with a linter before calling LoadFromYamlAsync.
Provide all required step types via stepTypes or assemblyPaths to avoid type resolution failures.
Pre-validate the workflow by deserializing with WorkflowSerializer directly to isolate parse vs. build errors.

When it happens

Trigger: Calling ProcessBuilder.LoadFromYamlAsync with malformed YAML, a YAML string that fails WorkflowSerializer.DeserializeFromYaml, missing step type registrations, or invalid workflow structure during BuildProcessAsync. Any exception inside the try block is wrapped.

Common situations: YAML has syntax errors (bad indentation, tabs); step types referenced in YAML are not provided via stepTypes or assemblyPaths; workflow schema mismatches the expected format after an SDK upgrade; assembly paths are wrong or assemblies fail to load.

Related errors

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