microsoft/aspire · error · DistributedApplicationException

Azure Container App environments

Error message

Azure Container App environments {collisionDetails}. Multiple environments with the same managed environment name cannot be deployed to one resource group. {string.Join(" ", guidance)}

What it means

ValidateManagedEnvironmentNames checks that multiple Azure Container App environments do not resolve to the same managed environment name, since Azure cannot deploy multiple managed environments with the same name into one resource group. On collision it throws a DistributedApplicationException with the collision details plus guidance strings (including a hint to remove WithAzdResourceNaming when azd naming mode contributed to the collision).

Solutions

Give each AddAzureContainerAppEnvironment a distinct explicit managed environment name
Remove WithAzdResourceNaming() or ensure azd-named environments resolve to distinct names
Consolidate to a single Container App environment if all container apps should share one environment

Example fix

// before
builder.AddAzureContainerAppEnvironment("envA").WithAzdResourceNaming();
builder.AddAzureContainerAppEnvironment("envB").WithAzdResourceNaming();
// after
builder.AddAzureContainerAppEnvironment("envA");
builder.AddAzureContainerAppEnvironment("envB");

Defensive patterns

Strategy: validation

Validate before calling

var names = builder.Resources.OfType<AzureContainerAppEnvironmentResource>().ToList();
if (names.GroupBy(e => GetManagedEnvironmentName(e)).Any(g => g.Count() > 1))
{
    throw new InvalidOperationException("Managed environment names must be unique per resource group");
}

Try / catch

try { await PublishAsync(model); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("managed environment name"))
{
    logger.LogError(ex, "Duplicate managed environment names detected");
}

Prevention

Give each Container App environment a unique explicit name
Avoid unconditionally using WithAzdResourceNaming across multiple environments
Share a single environment when apps belong in one environment

When it happens

Trigger: Declaring two or more AddAzureContainerAppEnvironment resources whose effective managed environment names collide — e.g. both left to azd-generated names via WithAzdResourceNaming(), or both configured with the same explicit name — evaluated during publish infrastructure generation.

Common situations: Copying an environment declaration and not renaming it; multiple teams/modules each adding a Container App environment with default naming into one resource group; azd naming mode collapsing distinct environments to identical names.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppExtensions.cs:209

                .ToHashSet();
            var guidance = new List<string>();

            if (namingModes.Contains(ManagedEnvironmentNamingMode.Legacy))
            {
                guidance.Add($"For environments using the default naming convention, call '{nameof(WithUniqueResourceNaming)}()'.");
            }

            if (namingModes.Contains(ManagedEnvironmentNamingMode.Unique))
            {
                guidance.Add($"For environments already using '{nameof(WithUniqueResourceNaming)}()', rename one or more resources or configure an explicit name resolver.");
            }

            if (namingModes.Contains(ManagedEnvironmentNamingMode.Azd))
            {
                guidance.Add($"For environments using '{nameof(WithAzdResourceNaming)}()', remove it or configure distinct managed environment names explicitly.");
            }

            throw new DistributedApplicationException(
                $"Azure Container App environments {collisionDetails}. Multiple environments with the same managed environment name cannot be deployed to one resource group. " +
                string.Join(" ", guidance));
        }

        private static string GetEffectiveNameKey(string expression)
        {
            // Normalize the two generated Bicep shapes that use the same 13-character resource-group token:
            //   take('cae-${uniqueString(resourceGroup().id)}', 60)
            //   'cae-${resourceToken}'
            // Evaluating take after substitution catches syntactically different expressions that deploy the
            // same physical name. Unknown shapes retain their expression as the key.
            var normalizedExpression = expression
                .Replace("${uniqueString(resourceGroup().id)}", ResourceGroupTokenPlaceholder, StringComparison.Ordinal)
                .Replace("${resourceToken}", ResourceGroupTokenPlaceholder, StringComparison.Ordinal);

            const string TakePrefix = "take('";
            const string TakeSeparator = "', ";
            if (normalizedExpression.StartsWith(TakePrefix, StringComparison.Ordinal) &&

View on GitHub (pinned to 25830f84bd)