What causes "Failed to connect to gRPC endpoint." in microsoft/autogen?

Verify AGENT_HOST is set to a reachable gRPC endpoint (e.g. http://localhost:5602) and the runtime service is up

microsoft/autogen · critical · Exception

Failed to connect to gRPC endpoint.

Error message

Failed to connect to gRPC endpoint.

What it means

Thrown by GrpcMessageRouter.EnsureConnected when RecreateChannel fails to establish a gRPC channel (returns null). The endpoint is taken from the AGENT_HOST environment variable, so the most common cause is a missing/unreachable AGENT_HOST or a malformed address.

Source

Thrown at dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcMessageRouter.cs:45

                              Guid clientId,
                              ILogger<GrpcAgentRuntime> logger,
                              CancellationToken shutdownCancellation = default)
    {
        _client = client;
        _clientId = clientId;
        _logger = logger;
        _shutdownCts = CancellationTokenSource.CreateLinkedTokenSource(shutdownCancellation);
    }

    public bool Connected { get => _channel is not null; }

    public void EnsureConnected()
    {
        _logger.LogInformation("Connecting to gRPC endpoint " + Environment.GetEnvironmentVariable("AGENT_HOST"));

        if (this.RecreateChannel(null) == null)
        {
            throw new Exception("Failed to connect to gRPC endpoint.");
        }
    }

    public AsyncDuplexStreamingCall<Message, Message> StreamingCall
    {
        get
        {
            if (_channel is { } channel)
            {
                return channel;
            }

            lock (_channelLock)
            {
                if (_channel is not null)
                {
                    return _channel;
                }

View on GitHub (pinned to 027ecf0a37)

Solutions

Verify AGENT_HOST is set to a reachable gRPC endpoint (e.g. http://localhost:5602) and the runtime service is up
Check connectivity manually (telnet/curl to the host:port) and fix DNS/port/firewall issues
In orchestrated environments, add readiness checks or startup retry so the worker only starts after the gRPC host accepts connections

Example fix

# before
# AGENT_HOST unset or wrong
dotnet run

# after
export AGENT_HOST=http://localhost:5602
dotnet run

Defensive patterns

Strategy: retry

Validate before calling

var host = Environment.GetEnvironmentVariable("AGENT_HOST");
if (string.IsNullOrWhiteSpace(host)) throw new InvalidOperationException("AGENT_HOST is not configured.");

Try / catch

for (int attempt = 0; ; attempt++)
{
    try { router.EnsureConnected(); break; }
    catch (Exception ex) when (attempt < 5)
    {
        _logger.LogWarning(ex, "gRPC connect failed (attempt {N}); retrying", attempt + 1);
        await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)));
    }
}

Prevention

Fail fast at startup if AGENT_HOST is unset
Use orchestration readiness probes so the worker starts only after the gRPC host is accepting connections
Log the resolved endpoint, not just the failure

When it happens

Trigger: AGENT_HOST not set, empty, or pointing at a host/port where no runtime gRPC service is listening; RecreateChannel failing to build a GrpcChannel (bad address format, TLS mismatch); network/DNS failure at connect time.

Common situations: Local development without the agent host running; container deployments missing the AGENT_HOST env var; service not ready when the worker starts (race at pod startup); wrong port or http/https scheme mismatch.

Related errors

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