{"record":{"id":"500fe6c4b0502bcd","repo":"microsoft/aspire","slug":"container-resource-container-name-uses-container-name","errorCode":null,"errorMessage":"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.","messagePattern":"Container resource '(.+?)' uses container name '(.+?)', which conflicts with the Aspire container tunnel container name '(.+?)'\\. Rename the container or disable the Aspire container tunnel\\.","errorType":"exception","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Dcp/ContainerCreator.cs","lineNumber":236,"sourceCode":"\n    private void ValidateContainerTunnelContainerNameConflicts(IEnumerable<IResource> modelContainerResources)\n    {\n        if (!_options.Value.EnableAspireContainerTunnel)\n        {\n            return;\n        }\n\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);","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Dcp/ContainerCreator.cs#L218-L254","documentation":"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.","triggerScenarios":"Calling .WithContainerName(\"<reserved tunnel name>\") (or adding a ContainerNameAnnotation) on any container resource while the container tunnel feature is enabled.","commonSituations":"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.","solutions":["Rename the container via the container-name annotation to a non-reserved name","Disable the Aspire container tunnel feature"],"exampleFix":"// before\nvar redis = builder.AddRedis(\"cache\").WithContainerName(\"aspire-container-tunnel\");\n// after\nvar redis = builder.AddRedis(\"cache\").WithContainerName(\"my-cache-container\");","handlingStrategy":"validation","validationCode":"if (containerName is not null && string.Equals(containerName, reservedTunnelContainerName, StringComparison.OrdinalIgnoreCase)) throw new InvalidOperationException(\"Container name conflicts with the reserved Aspire tunnel container name.\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check .WithContainerName values against the reserved tunnel name before use","Generate container names with a distinguishing prefix","Disable the container tunnel if explicit names must collide"],"tags":["containers","naming-conflict","annotations"],"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"}