{"record":{"id":"94c1f2dd13de5af0","repo":"microsoft/autogen","slug":"failed-to-connect-to-grpc-endpoint","errorCode":null,"errorMessage":"Failed to connect to gRPC endpoint.","messagePattern":"Failed to connect to gRPC endpoint\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"critical","filePath":"dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcMessageRouter.cs","lineNumber":45,"sourceCode":"                              Guid clientId,\n                              ILogger<GrpcAgentRuntime> logger,\n                              CancellationToken shutdownCancellation = default)\n    {\n        _client = client;\n        _clientId = clientId;\n        _logger = logger;\n        _shutdownCts = CancellationTokenSource.CreateLinkedTokenSource(shutdownCancellation);\n    }\n\n    public bool Connected { get => _channel is not null; }\n\n    public void EnsureConnected()\n    {\n        _logger.LogInformation(\"Connecting to gRPC endpoint \" + Environment.GetEnvironmentVariable(\"AGENT_HOST\"));\n\n        if (this.RecreateChannel(null) == null)\n        {\n            throw new Exception(\"Failed to connect to gRPC endpoint.\");\n        }\n    }\n\n    public AsyncDuplexStreamingCall<Message, Message> StreamingCall\n    {\n        get\n        {\n            if (_channel is { } channel)\n            {\n                return channel;\n            }\n\n            lock (_channelLock)\n            {\n                if (_channel is not null)\n                {\n                    return _channel;\n                }","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcMessageRouter.cs#L27-L63","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\n# AGENT_HOST unset or wrong\ndotnet run\n\n# after\nexport AGENT_HOST=http://localhost:5602\ndotnet run","handlingStrategy":"retry","validationCode":"var host = Environment.GetEnvironmentVariable(\"AGENT_HOST\");\nif (string.IsNullOrWhiteSpace(host)) throw new InvalidOperationException(\"AGENT_HOST is not configured.\");","typeGuard":null,"tryCatchPattern":"for (int attempt = 0; ; attempt++)\n{\n    try { router.EnsureConnected(); break; }\n    catch (Exception ex) when (attempt < 5)\n    {\n        _logger.LogWarning(ex, \"gRPC connect failed (attempt {N}); retrying\", attempt + 1);\n        await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)));\n    }\n}","preventionTips":["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"],"tags":["grpc","network","configuration","environment"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}