microsoft/aspire · error · DistributedApplicationException

Container resource ' ' uses container name ' ', which…

Error message

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.

What it means

Aspire reserves the container tunnel container name for its own tunnel container. When a container resource's ContainerNameAnnotation (the actual runtime container name, distinct from the resource name) matches that reserved name case-insensitively, preparation throws this exception to avoid two containers fighting over one runtime container name.

Solutions

1. Rename the container via the container-name annotation to a non-reserved name
2. Disable the Aspire container tunnel feature

Example fix

// before
var redis = builder.AddRedis("cache").WithContainerName("aspire-container-tunnel");
// after
var redis = builder.AddRedis("cache").WithContainerName("my-cache-container");

if (containerName is not null && string.Equals(containerName, reservedTunnelContainerName, StringComparison.OrdinalIgnoreCase)) throw new InvalidOperationException("Container name conflicts with the reserved Aspire tunnel container name.");

When it happens

Trigger: Calling .WithContainerName("<reserved tunnel name>") (or adding a ContainerNameAnnotation) on any container resource while the container tunnel feature is enabled.

Common situations: Users setting an explicit Docker container name that coincides with the reserved tunnel name, or reusing infrastructure-as-code naming conventions that collide; only when the tunnel is enabled.

Related errors

• Container resource ' ' uses network alias ' ', which…
• Container resource name
• Anonymous volumes cannot be read-only.
• ASPIRERADIUS084
• Bind mounts must specify a source path.

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

Appendix: source

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

    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)
            => string.Equals(name, ContainerTunnelContainerName, StringComparison.OrdinalIgnoreCase);
    }

    public bool IsReadyToCreate(RenderedModelResource<Container> resource, ContainerCreationContext cctx)
    {
        return !DcpModelUtilities.ShouldDeferCreateForExplicitStart(resource.ModelResource, resource.DcpResource.Spec.Start);

View on GitHub (pinned to 25830f84bd)