microsoft/semantic-kernel · error · KernelException

Only one `Default` handler is allowed in a group of event ha

Error message

Only one `Default` handler is allowed in a group of event handlers.

What it means

Thrown by DeclarativeEventHandlerGroupBuilder constructor when more than one condition of type DeclarativeProcessConditionType.Default is present in the conditions list. A handler group allows at most one Default (fallback) handler — multiple defaults create ambiguous routing.

Source

Thrown at dotnet/src/Experimental/Process.Core/ProcessAgentBuilder.cs:283

    /// </summary>
    /// <param name="conditions"></param>
    /// <exception cref="KernelException"></exception>
    public DeclarativeEventHandlerGroupBuilder(List<DeclarativeProcessCondition> conditions)
    {
        if (conditions is not null)
        {
            foreach (var condition in conditions)
            {
                if (condition is null)
                {
                    continue;
                }

                if (condition.Type == DeclarativeProcessConditionType.Default)
                {
                    if (this.DefaultHandler is not null)
                    {
                        throw new KernelException("Only one `Default` handler is allowed in a group of event handlers.");
                    }

                    if (!string.IsNullOrWhiteSpace(condition.Expression))
                    {
                        throw new KernelException("`Default` handlers must not have an eval expression.");
                    }

                    this.DefaultHandler = new DeclarativeEventHandlerBuilder(condition);
                }
                else if (condition.Type == DeclarativeProcessConditionType.Eval)
                {
                    this.EvalHandlers ??= [];
                    this.EvalHandlers.Add(new DeclarativeEventHandlerBuilder(condition));
                }
                else if (condition.Type == DeclarativeProcessConditionType.Always)
                {
                    if (this.DefaultHandler is not null)
                    {

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure only one condition with Type == Default exists per handler group.
2. Convert extra Default conditions to Eval conditions with explicit expressions if different behavior is needed.
3. Validate the conditions list for duplicate Default entries before passing it to OnComplete/OnError.

Example fix

// before
var conditions = new List<DeclarativeProcessCondition>
{
    new() { Type = DeclarativeProcessConditionType.Default },
    new() { Type = DeclarativeProcessConditionType.Default } // duplicate — throws
};
agent.OnComplete(conditions);

// after
var conditions = new List<DeclarativeProcessCondition>
{
    new() { Type = DeclarativeProcessConditionType.Default },
    new() { Type = DeclarativeProcessConditionType.Eval, Expression = "$.status == 'error'" }
};
agent.OnComplete(conditions);

public static void ValidateConditions(List<DeclarativeProcessCondition> conditions)
{
    var defaultCount = conditions.Count(c => c?.Type == DeclarativeProcessConditionType.Default);
    if (defaultCount > 1)
    {
        throw new KernelException("Only one Default handler is allowed per group.");
    }
}

When it happens

Trigger: Passing a List<DeclarativeProcessCondition> containing two or more conditions with Type == Default to OnComplete(conditions) or OnError(conditions) on an agent builder, or constructing a DeclarativeEventHandlerGroupBuilder with such a list.

Common situations: Defining agent event handlers in YAML or code with multiple Default cases in the same handler group. Copy-pasting handler definitions that accidentally duplicate the Default condition. Deserializing a malformed declarative process definition with duplicate defaults.

Related errors

• `Default` handlers must not have an eval expression.
• Only one `Always` handler is allowed in a group of event han
• `Always` handlers must not have an eval expression.
• Unknown condition type: {condition.Type}
• At least one action must be provided.

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