Event Hubs Emulator: "Connection refused" when using RunAsEmulator with Aspire despite .WaitFor(...) and healthy logs

[KieronAffelios]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I'm using .NET Aspire to migrate our development environment for a project that integrates with Azure Event Hubs. We're trying to run the Event Hubs emulator locally using RunAsEmulator().

Setup

Emulator started using:

var eventHubs = builder.AddAzureEventHubs("EventHubs")
    .RunAsEmulator(settings =>
        settings
            .WithVolume("/data/eventhubs") // originally present
    );

Event Hub declared:

var affeliosTransactionsEventHub = eventHubs.AddHub("TransactionsHub", "transactions-hub");

The consuming app uses EventProcessorClient:

processor = new EventProcessorClient(
    blobContainerClient,
    "$Default",
    settings.ConnectionStrings.GetOrDefault("TransactionsHub", settings.EventHubConnectionString),
    settings.TransactionsEventHub
);

What I've tried

1. Using .WaitFor(eventHubs) in Aspire to delay app startup.
2. Verified the container is running and listening on the assigned port (e.g., localhost:61969).
3. Removed .WithVolume(...) in case the emulator’s metadata store was failing to initialize.
4. Verified the connection string used is correct:
   Endpoint=sb://localhost:61969;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=***;UseDevelopmentEmulator=true;EntityPath=transactions-hub
5. Checked Docker logs (all is healthy)

Actual Behavior

Emulator logs say "Emulator Service is Successfully Up"
However, calling StartProcessingAsync() throws:

System.Net.Sockets.SocketException: No connection could be made because the target machine actively refused it

• Even though .WaitFor(eventHubs) is present, and Aspire shows the container as running, the emulator is not accepting TCP connections at the time the processor tries to connect.
• The EventProcessorClient also throws during partition retrieval (arg.Operation = "Retrieving list of partition identifiers from a Consumer Client").

Expected Behavior

• Aspire should delay starting dependent projects (or EventProcessorClient startup) until the Event Hubs emulator is fully accepting connections — not just "container is running".

• The .WaitFor(eventHubs) should ensure the emulator is "connectable", or offer a probe that waits for actual TCP/health readiness, not just container uptime.

• The emulator should surface clearer health signals or avoid reporting "successfully up" while metadata store is unhealthy.

Additional Notes

• The issue does not occur in production with real Azure Event Hubs — only with Aspire + RunAsEmulator.

Thanks for your great work — Aspire is a fantastic direction for development environments, and this would make it even more reliable.

My aspire config:

var eventHubs = builder.AddAzureEventHubs("EventHubs")
    .RunAsEmulator();

var storage = builder.AddAzureStorage("Storage")
    .RunAsEmulator();

var affeliosTransactionsStorage = storage.AddBlobs("TransactionsStorage");
var affeliosTransactionsEventHub = eventHubs.AddHub("TransactionsHub", "transactions-hub");

builder.AddProject<Projects.AffeliosPlatform>("AffeliosPlatform")
    .WithExternalHttpEndpoints()
    .WithReference(affeliosTransactionsEventHub)
    .WithEnvironment("TransactionsEventHub", affeliosTransactionsEventHub.Resource.HubName)
    .WithReference(affeliosTransactionsStorage)
    .WaitFor(eventHubs)
    .WaitFor(affeliosTransactionsEventHub)
    .WaitFor(affeliosTransactionsStorage);

Here is how I initialize the EventHubProducerClient which I believe works:

new EventHubProducerClient(settings.ConnectionStrings.GetOrDefault("TransactionsHub", settings.EventHubConnectionString), settings.TransactionsEventHub);

Here is how I initialize the BlobContainerClient and EventProcessorClient

blobContainerClient = new BlobContainerClient(settings.ConnectionStrings.GetOrDefault("TransactionsStorage", settings.StorageConnectionString), checkpointName);
processor = new EventProcessorClient(
    blobContainerClient,
    "$Default",
    settings.ConnectionStrings.GetOrDefault("TransactionsHub", settings.EventHubConnectionString),
    settings.TransactionsEventHub);

I'm happy to provide any additional information/docker logs if need be.

[davidfowl]

Something else is going on if it's saying it is healthy AFAIK we use the emulator health check to verify if it is healthy. Does it connect later or is the emulator incorrect about its health?

This is a working sample using event hubs https://github.com/dotnet/aspire/tree/main/playground/AspireEventHub

cc @oising for more thoughts.