What causes "Custom container networks are not supported yet." in microsoft/aspire?

Remove ContainerNetworkAliasAnnotation calls that target non-default networks, or point them at the default Aspire container network

microsoft/aspire · error · InvalidOperationException

Custom container networks are not supported yet.

Error message

Custom container networks are not supported yet.

What it means

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.

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

Example fix

// before
builder.AddContainer("api", "image")
       .WithContainerNetworkAlias("my-custom-network", "api.local");
// after
builder.AddContainer("api", "image")
       .WithContainerNetworkAlias(KnownNetworkIdentifiers.DefaultAspireContainerNetwork, "api.local");

Defensive patterns

Strategy: validation

Validate before calling

foreach (var alias in container.Annotations.OfType<ContainerNetworkAliasAnnotation>())
{
    if (alias.Network != KnownNetworkIdentifiers.DefaultAspireContainerNetwork)
    {
        throw new NotSupportedException($"Network '{alias.Network}' is not supported; use the default Aspire container network.");
    }
}

Type guard

bool UsesDefaultNetwork(ContainerNetworkAliasAnnotation a) =>
    a.Network == KnownNetworkIdentifiers.DefaultAspireContainerNetwork;

Try / catch

try
{
    creator.PrepareObjects(container, ...);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Custom container networks"))
{
    // Strip the custom alias or inform the user custom networks are unsupported.
}

Prevention

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

When it happens

Trigger: PrepareObjects encountering a ContainerNetworkAliasAnnotation whose Network is not KnownNetworkIdentifiers.DefaultAspireContainerNetwork — i.e. calling the network-alias API with a custom network name.

Common situations: 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.

Related errors

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

Appendix: source

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

                ctr.Spec.PullPolicy = pullPolicy switch
                {
                    ImagePullPolicy.Default => null,
                    ImagePullPolicy.Always => ContainerPullPolicy.Always,
                    ImagePullPolicy.Missing => ContainerPullPolicy.Missing,
                    ImagePullPolicy.Never => ContainerPullPolicy.Never,
                    _ => throw new InvalidOperationException($"Unknown pull policy '{Enum.GetName(typeof(ImagePullPolicy), pullPolicy)}' for container '{container.Name}'")
                };
            }

            ctr.Annotate(CustomResource.ResourceNameAnnotation, container.Name);
            ctr.Annotate(CustomResource.OtelServiceNameAnnotation, container.Name);
            ctr.Annotate(CustomResource.OtelServiceInstanceIdAnnotation, container.GetOtelServiceInstanceId(containerObjectInstance));
            DcpExecutor.SetInitialResourceState(container, ctr);

            var aanns = container.Annotations.OfType<ContainerNetworkAliasAnnotation>().ToImmutableArray();
            if (aanns.Any(a => a.Network != KnownNetworkIdentifiers.DefaultAspireContainerNetwork))
            {
                throw new InvalidOperationException("Custom container networks are not supported yet.");
            }

            ctr.Spec.Networks = new List<ContainerNetworkConnection>
            {
                new ContainerNetworkConnection
                {
                    Name = KnownNetworkIdentifiers.DefaultAspireContainerNetwork.Value,
                    Aliases = aanns.Select(a => a.Alias)
                                .Prepend($"{container.Name}.dev.internal")
                                .Prepend(container.Name)
                                .ToList()
                }
            };

            if (container.TryGetLastAnnotation<ExplicitStartupAnnotation>(out _))
            {
                ctr.Spec.Start = false;
            }

View on GitHub (pinned to 25830f84bd)