microsoft/autogen · error · InvalidOperationException

No handler method found for interface {interface_.FullName}

Error message

No handler method found for interface {interface_.FullName}

What it means

Thrown in BaseAgent's handler-invoker discovery when an IHandle<> or IHandle<,> interface on the agent type does not expose a public instance HandleAsync method via reflection. Because the interfaces are known to define HandleAsync, this is essentially an internal invariant failure — typically triggered by reflection visibility issues or an incompatible interface definition from a mismatched package version.

Source

Thrown at dotnet/src/Microsoft.AutoGen/Core/BaseAgent.cs:74

        this.handlerInvokers = this.ReflectInvokers();
    }

    private Dictionary<Type, HandlerInvoker> ReflectInvokers()
    {
        Type realType = this.GetType();

        IEnumerable<Type> candidateInterfaces =
            realType.GetInterfaces()
                    .Where(i => i.IsGenericType &&
                            (i.GetGenericTypeDefinition() == typeof(IHandle<>) ||
                            (i.GetGenericTypeDefinition() == typeof(IHandle<,>))));

        Dictionary<Type, HandlerInvoker> invokers = new();
        foreach (Type interface_ in candidateInterfaces)
        {
            MethodInfo handleAsync = interface_.GetMethod(nameof(IHandle<object>.HandleAsync), BindingFlags.Instance | BindingFlags.Public)
                                     ?? throw new InvalidOperationException($"No handler method found for interface {interface_.FullName}");

            HandlerInvoker invoker = new(handleAsync, this);
            invokers.Add(interface_.GetGenericArguments()[0], invoker);
        }

        return invokers;
    }

    public async ValueTask<object?> OnMessageAsync(object message, MessageContext messageContext)
    {
        // Determine type of message, then get handler method and invoke it
        var messageType = message.GetType();
        if (this.handlerInvokers.TryGetValue(messageType, out var handlerInvoker))
        {
            return await handlerInvoker.InvokeAsync(message, messageContext);
        }

        return null;

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Align all Microsoft.AutoGen package versions across the project so IHandle<>/IHandle<,> come from a single assembly identity
2. Implement the framework's IHandle<T> interface directly (public HandleAsync) rather than a lookalike interface
3. Clean bin/obj and restore to eliminate stale mixed-version assemblies

Example fix

<!-- before -->
<ItemGroup>
  <PackageReference Include="Microsoft.AutoGen.Core" Version="0.x" />
  <PackageReference Include="Microsoft.AutoGen.Agents" Version="0.y" /> <!-- mismatched -->
</ItemGroup>

<!-- after -->
<ItemGroup>
  <PackageReference Include="Microsoft.AutoGen.Core" Version="0.z" />
  <PackageReference Include="Microsoft.AutoGen.Agents" Version="0.z" />
</ItemGroup>

foreach (var i in typeof(TAgent).GetInterfaces().Where(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IHandle<>)))
{
    if (i.GetMethod(nameof(IHandle<object>.HandleAsync), BindingFlags.Instance | BindingFlags.Public) is null)
        throw new InvalidOperationException($"Handler surface broken on {i.FullName}; check package version alignment");
}

try { var agent = Activator.CreateInstance<TAgent>(); } catch (InvalidOperationException ex) when (ex.Message.Contains("No handler method found")) { _logger.LogError(ex, "IHandle contract mismatch; align Microsoft.AutoGen package versions"); throw; }

When it happens

Trigger: Agent type implements IHandle<T> from a different assembly version whose HandleAsync signature differs (e.g. parameter count changed); a custom interface definition shadowing IHandle<>; COM/transparent-proxy types where GetMethod does not resolve normally.

Common situations: Mixing versions of Microsoft.AutoGen packages so IHandle<T> resolves to different definitions in one type graph; building custom handler abstractions that mimic IHandle<>; rare dynamic-proxy agents.

Related errors

• Target must be provided for non-static methods
• Method {methodInfo.Name} must return a ValueTask or ValueTas
• Unable to convert "{value}" to enum {typeToConvert}.
• Could not create chat manager
• Could not create chat manager; make sure that it contains a

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/5d40ecd00544ab2e. Report an issue: GitHub.