microsoft/aspire · error · InvalidOperationException

Failed to authenticate to the AppHost server.

Error message

Failed to authenticate to the AppHost server.

What it means

Thrown by AppHostRpcClient.ConnectAsync when the AppHost server rejects the CLI's authentication handshake — the RPC 'authenticate' call returned false even though the transport connected. The CLI refuses to create an AppHostRpcClient over an unauthenticated stream to prevent talking to an untrusted or mismatched server.

Solutions

1. Restart the AppHost/CLI session so a fresh authentication token is issued
2. Delete stale socket/token files in the temp/sockets directory and retry
3. Ensure CLI and AppHost server versions match (update or reinstall aspire)
4. Verify no other process is bound to the same socket path

Example fix

// before
aspire run  // reuses stale socket from crashed session
// after
rm -rf $TMPDIR/aspire.* && aspire run

if (!File.Exists(socketPath))
    throw new InvalidOperationException("Socket path does not exist; start the server first.");

try
{
    var client = await AppHostRpcClient.ConnectAsync(...);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("authenticate"))
{
    // discard stale session state and retry once with a fresh token
}

When it happens

Trigger: Calling ConnectAsync when the authenticationToken sent via the 'authenticate' RPC does not match what the AppHost server expects, so the server returns false.

Common situations: Stale socket/token files left over from a previous session, a different AppHost server process owning the socket path, version mismatch between CLI and server, or another process squatting on the socket.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Failed to connect to RPC server at
• -32000
• Already connected to AppHost backchannel.
• An input name is required when uploading a file.
• An interaction ID is required when uploading a file.

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

Appendix: source

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

        try
        {
            var formatter = BackchannelJsonSerializerContext.CreateRpcMessageFormatter();
            var handler = new HeaderDelimitedMessageHandler(stream, stream, formatter);
            jsonRpc = new JsonRpc(handler)
            {
                ActivityTracingStrategy = new ActivityTracingStrategy()
            };
            jsonRpc.StartListening();

            var authenticated = await jsonRpc.InvokeWithProfilingAsync<bool>(
                profilingTelemetry,
                ConnectionName,
                "authenticate",
                [authenticationToken],
                cancellationToken).ConfigureAwait(false);
            if (!authenticated)
            {
                throw new InvalidOperationException("Failed to authenticate to the AppHost server.");
            }

            return new AppHostRpcClient(stream, jsonRpc, profilingTelemetry);
        }
        catch
        {
            jsonRpc?.Dispose();
            await stream.DisposeAsync();
            throw;
        }
    }

    /// <inheritdoc />
    public Task<RuntimeSpec> GetRuntimeSpecAsync(string languageId, CancellationToken cancellationToken)
        => InvokeAsync<RuntimeSpec>("getRuntimeSpec", [languageId], cancellationToken);

    /// <inheritdoc />
    public Task<Dictionary<string, string>> ScaffoldAppHostAsync(

View on GitHub (pinned to 25830f84bd)