{"record":{"id":"c94c3f453fd6558b","repo":"microsoft/aspire","slug":"container-resource-container-name-uses-network-alias","errorCode":null,"errorMessage":"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.","messagePattern":"Container resource '(.+?)' uses network alias '(.+?)', which conflicts with the Aspire container tunnel container name '(.+?)'\\. Rename the alias or disable the Aspire container tunnel\\.","errorType":"exception","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Dcp/ContainerCreator.cs","lineNumber":243,"sourceCode":"\n        foreach (var container in modelContainerResources)\n        {\n            if (IsContainerTunnelContainerName(container.Name))\n            {\n                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.\");\n            }\n\n            if (container.TryGetLastAnnotation<ContainerNameAnnotation>(out var containerNameAnnotation) &&\n                IsContainerTunnelContainerName(containerNameAnnotation.Name))\n            {\n                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.\");\n            }\n\n            foreach (var aliasAnnotation in container.Annotations.OfType<ContainerNetworkAliasAnnotation>())\n            {\n                if (IsContainerTunnelContainerName(aliasAnnotation.Alias))\n                {\n                    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.\");\n                }\n            }\n        }\n\n        static bool IsContainerTunnelContainerName(string name)\n            => string.Equals(name, ContainerTunnelContainerName, StringComparison.OrdinalIgnoreCase);\n    }\n\n    public bool IsReadyToCreate(RenderedModelResource<Container> resource, ContainerCreationContext cctx)\n    {\n        return !DcpModelUtilities.ShouldDeferCreateForExplicitStart(resource.ModelResource, resource.DcpResource.Spec.Start);\n    }\n\n    public async Task CreateObjectAsync(RenderedModelResource<Container> cr, ContainerCreationContext cctx, ILogger logger, IDcpObjectFactory factory, CancellationToken cancellationToken)\n    {\n        var hostDependencies = (await GetHostDependenciesAsync(cr.ModelResource, cancellationToken).ConfigureAwait(false)).ToImmutableArray();\n\n        if (hostDependencies.Any())","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Dcp/ContainerCreator.cs#L225-L261","documentation":"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.","triggerScenarios":"Calling .WithContainerNetworkAlias(...) (or adding ContainerNetworkAliasAnnotation) with an alias equal to the reserved tunnel container name while the container tunnel is enabled.","commonSituations":"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.","solutions":["Change the network alias to a non-reserved value","Disable the Aspire container tunnel feature"],"exampleFix":"// before\n.WithContainerNetworkAlias(\"aspire-container-tunnel\")\n// after\n.WithContainerNetworkAlias(\"my-service-alias\")","handlingStrategy":"validation","validationCode":"foreach (var alias in aliases) if (string.Equals(alias, reservedTunnelContainerName, StringComparison.OrdinalIgnoreCase)) throw new InvalidOperationException($\"Alias '{alias}' conflicts with the reserved tunnel container name.\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never derive aliases directly from raw container names without filtering reserved names","Centralize alias creation in a helper that rejects reserved names","Document reserved names for the team"],"tags":["containers","dns","naming-conflict"],"backgroundTag":"name-collision","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}