microsoft/aspire · error · DistributedApplicationException

One or more container network tunnel proxies did not start…

Error message

One or more container network tunnel proxies did not start successfully: {details}

What it means

Aspire starts network tunnel proxy objects so containers can reach host services. WaitForTunnelProxyAsync observes the proxy state; if the proxy failed or never reached a stable running state, a DistributedApplicationException is thrown including the proxy name and its status message or current state.

Solutions

1. Read the details in the message for the proxy's status message or last state
2. Check the container runtime is running and healthy (docker ps / podman ps)
3. Look for port conflicts or image pull errors for the tunnel proxy
4. Retry after fixing the environment; restart DCP/container runtime if stuck

// Verify container runtime health before starting the app host
var psi = System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo("docker", "info") { RedirectStandardOutput = true }); psi!.WaitForExit(5000); if (psi.ExitCode != 0) throw new InvalidOperationException("Container runtime not healthy");

try { await app.StartAsync(); } catch (DistributedApplicationException ex) when (ex.Message.Contains("tunnel proxies did not start")) { logger.LogError(ex, "Tunnel proxy failed: {Details}", ExtractDetails(ex.Message)); /* fix env, then retry */ }

When it happens

Trigger: CreateTunnelProxyResourceAsync waits on a container network tunnel proxy; the proxy enters a Failed state (status message in details) or times out without reaching running (state shown in details).

Common situations: Tunnel proxy image pull failures, port conflicts on the host, container runtime (Docker/Podman) not healthy, resource exhaustion preventing the proxy container from starting.

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

• Container tunnel service
• Custom container networks are not supported yet.
• Host endpoint ' ' on resource ' ' should have an associated…
• Service ' ' refers to endpoint ' ' that does not exist
• Address prefix must be a string or a parameter resource…

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

Appendix: source

Thrown at src/Aspire.Hosting/Dcp/ContainerCreator.cs:631

        var observedStatus = observedProxy.Status;
        var running = observedStatus is not null &&
            string.Equals(observedStatus.State, ContainerNetworkTunnelProxyState.Running, StringComparison.Ordinal);

        const string noDetailsAvailable = "(no additional error details available)";
        if (failed)
        {
            _logger.LogError(
                "Container network tunnel proxy '{Name}' failed: {Details}",
                observedProxy.Metadata.Name,
                observedProxy.Status?.Message ?? noDetailsAvailable);
        }

        if (failed || !running)
        {
            var details = failed
                ? $"'{observedProxy.Metadata.Name}': {observedProxy.Status?.Message ?? noDetailsAvailable}"
                : $"'{observedProxy.Metadata.Name}': did not reach a stable state (current state: '{observedProxy.Status?.State ?? "(unknown)"}')";
            throw new DistributedApplicationException(
                $"One or more container network tunnel proxies did not start successfully: {details}");
        }
    }

    internal async Task<IEnumerable<HostResourceWithEndpoints>> GetHostDependenciesAsync(IResource resource, CancellationToken cancellationToken)
    {
        var allDependencies = await ResourceExtensions.GetResourceDependenciesAsync(
            resource,
            _executionContext,
            new ResourceDependencyDiscoveryOptions
            {
                DiscoveryMode = ResourceDependencyDiscoveryMode.DirectOnly,
                CacheAnnotationCallbackResults = true
            },
            cancellationToken
        ).ConfigureAwait(false);

        List<HostResourceWithEndpoints> hostDependencies = [.. allDependencies.Select(HostResourceWithEndpoints.Create).OfType<HostResourceWithEndpoints>()];

View on GitHub (pinned to 25830f84bd)