microsoft/semantic-kernel · error · KernelException

Failed to serialize Enum Name

Error message

Failed to serialize Enum Name

What it means

Thrown by the internal `DictionaryLookupNamingPolicy` constructor when the `dictionary` argument passed to it is null. This naming policy maps enum names to serialized strings during JSON serialization; a null lookup table is a programmer error in the serializer setup, not a user-data problem. It is a KernelException.

Source

Thrown at dotnet/src/Experimental/Process.Core/WorkflowSerializer.cs:222

            }

            return this._baseConverter.CreateConverter(typeToConvert, options);
        }
    }

    internal class JsonNamingPolicyDecorator : JsonNamingPolicy
    {
        private readonly JsonNamingPolicy? _underlyingNamingPolicy;

        public JsonNamingPolicyDecorator(JsonNamingPolicy? underlyingNamingPolicy) => this._underlyingNamingPolicy = underlyingNamingPolicy;
        public override string ConvertName(string name) => this._underlyingNamingPolicy?.ConvertName(name) ?? name;
    }

    internal class DictionaryLookupNamingPolicy : JsonNamingPolicyDecorator
    {
        private readonly Dictionary<string, string> _dictionary;

        public DictionaryLookupNamingPolicy(Dictionary<string, string> dictionary, JsonNamingPolicy? underlyingNamingPolicy) : base(underlyingNamingPolicy) => this._dictionary = dictionary ?? throw new KernelException("Failed to serialize Enum Name");
        public override string ConvertName(string name) => this._dictionary.TryGetValue(name, out var value) ? value : base.ConvertName(name);
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Report/fix the upstream code that produces a null enum-name dictionary (the query at the call site should yield an empty dict, not null).
2. Ensure any custom use passes a non-null dictionary, defaulting to `new()` when empty.
3. Upgrade the Process.Core package in case the null-source bug is already patched.

Example fix

// before
return new DictionaryLookupNamingPolicy(null, this._namingPolicy);
// after
return new DictionaryLookupNamingPolicy(query ?? new Dictionary<string,string>(), this._namingPolicy);

// If you invoke internal serializer plumbing, never pass null.
var lookup = query?.ToDictionary(p => p.Item1, p => p.Item2) ?? new Dictionary<string, string>();
var policy = new DictionaryLookupNamingPolicy(lookup, namingPolicy);

bool IsNonNullDictionary(Dictionary<string,string> d) => d is not null;

try { serializer.Serialize(obj); }
catch (KernelException ex) when (ex.Message.Contains("Failed to serialize Enum Name"))
{ _logger.LogError(ex, "Enum-name lookup dictionary was null; serializer misconfigured."); throw; }

When it happens

Trigger: The enum-name query that feeds `DictionaryLookupNamingPolicy` produces a null dictionary (e.g. an extension method returning null) and that null is passed into the constructor; custom code instantiates this internal class with a null dictionary.

Common situations: Internal serializer bug or reflection-based query returning null unexpectedly; custom serialization pipeline wiring that bypasses the null-coalescing guard upstream; this is rarely hit by end users since the class is internal.

Related errors

• Failed to parse schema.
• Unsupported target type
• The process must have an Id set
• Failed to deserialize schema.
• Attempt to build a workflow node from step with no Id

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