{"record":{"id":"3aee22628e495132","repo":"microsoft/aspire","slug":"custom-container-networks-are-not-supported-yet","errorCode":null,"errorMessage":"Custom container networks are not supported yet.","messagePattern":"Custom container networks are not supported yet\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Dcp/ContainerCreator.cs","lineNumber":181,"sourceCode":"                ctr.Spec.PullPolicy = pullPolicy switch\n                {\n                    ImagePullPolicy.Default => null,\n                    ImagePullPolicy.Always => ContainerPullPolicy.Always,\n                    ImagePullPolicy.Missing => ContainerPullPolicy.Missing,\n                    ImagePullPolicy.Never => ContainerPullPolicy.Never,\n                    _ => throw new InvalidOperationException($\"Unknown pull policy '{Enum.GetName(typeof(ImagePullPolicy), pullPolicy)}' for container '{container.Name}'\")\n                };\n            }\n\n            ctr.Annotate(CustomResource.ResourceNameAnnotation, container.Name);\n            ctr.Annotate(CustomResource.OtelServiceNameAnnotation, container.Name);\n            ctr.Annotate(CustomResource.OtelServiceInstanceIdAnnotation, container.GetOtelServiceInstanceId(containerObjectInstance));\n            DcpExecutor.SetInitialResourceState(container, ctr);\n\n            var aanns = container.Annotations.OfType<ContainerNetworkAliasAnnotation>().ToImmutableArray();\n            if (aanns.Any(a => a.Network != KnownNetworkIdentifiers.DefaultAspireContainerNetwork))\n            {\n                throw new InvalidOperationException(\"Custom container networks are not supported yet.\");\n            }\n\n            ctr.Spec.Networks = new List<ContainerNetworkConnection>\n            {\n                new ContainerNetworkConnection\n                {\n                    Name = KnownNetworkIdentifiers.DefaultAspireContainerNetwork.Value,\n                    Aliases = aanns.Select(a => a.Alias)\n                                .Prepend($\"{container.Name}.dev.internal\")\n                                .Prepend(container.Name)\n                                .ToList()\n                }\n            };\n\n            if (container.TryGetLastAnnotation<ExplicitStartupAnnotation>(out _))\n            {\n                ctr.Spec.Start = false;\n            }","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Dcp/ContainerCreator.cs#L163-L199","documentation":"Aspire currently supports connecting containers only to the default Aspire container network. If a ContainerResource carries a ContainerNetworkAliasAnnotation targeting any other network, ContainerCreator refuses to prepare the container because custom networks are not yet implemented. The feature gate is explicit rather than silently ignoring the alias.","triggerScenarios":"PrepareObjects encountering a ContainerNetworkAliasAnnotation whose Network is not KnownNetworkIdentifiers.DefaultAspireContainerNetwork — i.e. calling the network-alias API with a custom network name.","commonSituations":"Attempting to attach a container to a user-defined Docker network via aliases before the feature shipped; copying sample code referencing custom networks; upgrading from a setup that assumed multi-network support.","solutions":["Remove ContainerNetworkAliasAnnotation calls that target non-default networks, or point them at the default Aspire container network","Check the Aspire version/release notes for custom container network support before using the API","Wrap container preparation and surface a clear 'custom networks unsupported' message in publishing tooling"],"exampleFix":"// before\nbuilder.AddContainer(\"api\", \"image\")\n       .WithContainerNetworkAlias(\"my-custom-network\", \"api.local\");\n// after\nbuilder.AddContainer(\"api\", \"image\")\n       .WithContainerNetworkAlias(KnownNetworkIdentifiers.DefaultAspireContainerNetwork, \"api.local\");","handlingStrategy":"validation","validationCode":"foreach (var alias in container.Annotations.OfType<ContainerNetworkAliasAnnotation>())\n{\n    if (alias.Network != KnownNetworkIdentifiers.DefaultAspireContainerNetwork)\n    {\n        throw new NotSupportedException($\"Network '{alias.Network}' is not supported; use the default Aspire container network.\");\n    }\n}","typeGuard":"bool UsesDefaultNetwork(ContainerNetworkAliasAnnotation a) =>\n    a.Network == KnownNetworkIdentifiers.DefaultAspireContainerNetwork;","tryCatchPattern":"try\n{\n    creator.PrepareObjects(container, ...);\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Custom container networks\"))\n{\n    // Strip the custom alias or inform the user custom networks are unsupported.\n}","preventionTips":["Only attach network aliases to KnownNetworkIdentifiers.DefaultAspireContainerNetwork","Check release notes for custom-network support before adopting the API","Pre-validate container annotations in custom publishers before PrepareObjects","Fall back to default-network aliases with a warning when custom networks are requested"],"tags":["containers","networking","dcp"],"backgroundTag":"feature-not-enabled","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"}