microsoft/aspire · error · DistributedApplicationException

Container resource ' ' uses network alias ' ', which…

Error message

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.

What it means

Container network aliases let other containers resolve a container by DNS name on a network. Aspire reserves the tunnel container's name, so if any ContainerNetworkAliasAnnotation on a container matches the reserved tunnel container name (case-insensitive), validation throws to prevent DNS alias conflicts on the shared network.

Solutions

1. Change the network alias to a non-reserved value
2. Disable the Aspire container tunnel feature

Example fix

// before
.WithContainerNetworkAlias("aspire-container-tunnel")
// after
.WithContainerNetworkAlias("my-service-alias")

foreach (var alias in aliases) if (string.Equals(alias, reservedTunnelContainerName, StringComparison.OrdinalIgnoreCase)) throw new InvalidOperationException($"Alias '{alias}' conflicts with the reserved tunnel container name.");

When it happens

Trigger: Calling .WithContainerNetworkAlias(...) (or adding ContainerNetworkAliasAnnotation) with an alias equal to the reserved tunnel container name while the container tunnel is enabled.

Common situations: Mirroring the container's runtime name as an alias, or bulk-applying aliases generated from container names, when one happens to equal the reserved tunnel name.

Related errors

• Container resource ' ' uses container name ' ', 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/c94c3f453fd6558b. Report an issue: GitHub.

Appendix: source

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

        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);
    }

    public async Task CreateObjectAsync(RenderedModelResource<Container> cr, ContainerCreationContext cctx, ILogger logger, IDcpObjectFactory factory, CancellationToken cancellationToken)
    {
        var hostDependencies = (await GetHostDependenciesAsync(cr.ModelResource, cancellationToken).ConfigureAwait(false)).ToImmutableArray();

        if (hostDependencies.Any())

View on GitHub (pinned to 25830f84bd)