microsoft/aspire · error · InvalidOperationException

Failed to connect to RPC server at

Error message

Failed to connect to RPC server at {socketPath}

What it means

Thrown by AppHostRpcClient.ConnectToServerAsync when connecting over a NamedPipeStream repeatedly throws IOException (the pipe endpoint isn't accepting connections) until retry attempts are exhausted. The CLI gives up waiting for the pipe-based RPC server to become reachable and reports the socket path it was trying.

Solutions

1. Check the AppHost server process is running and inspect its logs for startup failure
2. Increase the retry/timeout budget if the server starts slowly
3. Restart the session to get a fresh socket path
4. Verify named pipes are functional in your environment (containers, Windows services)

Example fix

// before
var client = await AppHostRpcClient.ConnectToServerAsync(pipePath); // throws if server slow to start
// after
await WaitForServerReadyAsync(pipePath, timeout: TimeSpan.FromSeconds(30));
var client = await AppHostRpcClient.ConnectToServerAsync(pipePath);

// Ensure the server is listening before connecting
if (!WaitForPipeAvailability(pipePath, TimeSpan.FromSeconds(30)))
    throw new TimeoutException($"RPC server pipe {pipePath} not ready.");

try
{
    var client = await AppHostRpcClient.ConnectToServerAsync(pipePath, ct);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Failed to connect"))
{
    logger.LogError("RPC server at {Path} unreachable; is the AppHost running?", pipePath);
}

When it happens

Trigger: Calling ConnectToServerAsync (via stream) when every NamedPipeClientStream connect attempt throws IOException within the retry window, e.g. the server never created/accepted the pipe.

Common situations: AppHost server process crashed at startup, server is still starting and slower than the retry budget, pipe name mismatch, or running in a sandbox/container where named pipes are unavailable.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Failed to authenticate to the AppHost server.
• not connected to AppHost
• -32000
• -32603
• Already connected to AppHost backchannel.

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/757baaaca9226152. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Cli/Projects/AppHostRpcClient.cs:213

            {
                while ((DateTimeOffset.UtcNow - startTime) < TimeSpan.FromSeconds(ConnectionTimeoutSeconds))
                {
                    try
                    {
                        await pipeClient.ConnectAsync(cancellationToken).ConfigureAwait(false);
                        return pipeClient;
                    }
                    catch (TimeoutException)
                    {
                        await Task.Delay(100, cancellationToken).ConfigureAwait(false);
                    }
                    catch (IOException)
                    {
                        await Task.Delay(100, cancellationToken).ConfigureAwait(false);
                    }
                }

                throw new InvalidOperationException($"Failed to connect to RPC server at {socketPath}");
            }
            catch
            {
                pipeClient.Dispose();
                throw;
            }
        }
        else
        {
            var socket = new Socket(AddressFamily.Unix, SocketType.Stream, ProtocolType.Unspecified);
            try
            {
                var endpoint = new UnixDomainSocketEndPoint(socketPath);

                while ((DateTimeOffset.UtcNow - startTime) < TimeSpan.FromSeconds(ConnectionTimeoutSeconds))
                {
                    try
                    {

View on GitHub (pinned to 25830f84bd)