microsoft/aspire · error · DistributedApplicationException

Container resource name

Error message

Container resource name '{container.Name}' conflicts with the Aspire container tunnel container name '{ContainerTunnelContainerName}'. Rename the resource or disable the Aspire container tunnel.

What it means

Aspire reserves a special container name for its container tunnel feature. During DCP object preparation, every model container resource is checked and if its resource name matches the reserved tunnel container name (case-insensitive), startup fails with this DistributedApplicationException. The check exists because creating two containers with the same name would collide at the container runtime.

Solutions

1. Rename the container resource so it no longer matches the reserved tunnel container name
2. Disable the Aspire container tunnel feature if the name must be kept

Example fix

// before
builder.AddContainer("aspire-container-tunnel", "image:tag");
// after
builder.AddContainer("my-tunnel-sidecar", "image:tag");

if (string.Equals(resource.Name, reservedTunnelContainerName, StringComparison.OrdinalIgnoreCase)) throw new InvalidOperationException($"Resource name '{resource.Name}' conflicts with the reserved Aspire tunnel container name.");

When it happens

Trigger: Creating a container resource whose resource name equals the Aspire container tunnel container name (e.g. via AddContainer(name, ...) with the reserved name) while the container tunnel feature is enabled.

Common situations: Users naming a resource to match the tunnel container (copying infrastructure names), or code that generates container names that accidentally collide with the reserved tunnel name; only occurs when the container tunnel is enabled.

Related errors

• Container resource ' ' uses container name ' ', which…
• Container resource ' ' uses network alias ' ', which…
• Could not open connection to
• Anonymous volumes cannot be read-only.
• AppHost server process exited before the RPC connection…

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

Appendix: source

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

        if (resource.TryGetParentProcessLifetime(out var parentProcessId, out var parentProcessTimestamp))
        {
            spec.MonitorPid = parentProcessId;
            spec.MonitorTimestamp = parentProcessTimestamp;
        }
    }

    private void ValidateContainerTunnelContainerNameConflicts(IEnumerable<IResource> modelContainerResources)
    {
        if (!_options.Value.EnableAspireContainerTunnel)
        {
            return;
        }

        foreach (var container in modelContainerResources)
        {
            if (IsContainerTunnelContainerName(container.Name))
            {
                throw new DistributedApplicationException($"Container resource name '{container.Name}' conflicts with the Aspire container tunnel container name '{ContainerTunnelContainerName}'. Rename the resource or disable the Aspire container tunnel.");
            }

            if (container.TryGetLastAnnotation<ContainerNameAnnotation>(out var containerNameAnnotation) &&
                IsContainerTunnelContainerName(containerNameAnnotation.Name))
            {
                throw new DistributedApplicationException($"Container resource '{container.Name}' uses container name '{containerNameAnnotation.Name}', which conflicts with the Aspire container tunnel container name '{ContainerTunnelContainerName}'. Rename the container or disable the Aspire container tunnel.");
            }

            foreach (var aliasAnnotation in container.Annotations.OfType<ContainerNetworkAliasAnnotation>())
            {
                if (IsContainerTunnelContainerName(aliasAnnotation.Alias))
                {
                    throw new DistributedApplicationException($"Container resource '{container.Name}' uses network alias '{aliasAnnotation.Alias}', which conflicts with the Aspire container tunnel container name '{ContainerTunnelContainerName}'. Rename the alias or disable the Aspire container tunnel.");
                }
            }
        }

        static bool IsContainerTunnelContainerName(string name)

View on GitHub (pinned to 25830f84bd)