microsoft/aspire · error · DistributedApplicationException

Cannot configure the RabbitMQ resource

Error message

Cannot configure the RabbitMQ resource '{builder.Resource.Name}' to enable the management plugin as it uses an unrecognized container image registry, name, or tag.

What it means

WithManagementPlugin enables RabbitMQ's management UI by adding an HTTP endpoint on port 15672, but only when it recognizes the container image (registry, name, tag). If the image was customized to something it cannot classify (e.g. a custom registry or a non-standard tag), it throws DistributedApplicationException because enabling the plugin requires modifying the image/tag it does not understand.

Solutions

Use a standard RabbitMQ image with a recognized version tag (e.g. '3' or '3-management') before calling WithManagementPlugin.
If a mirror registry is required, also use WithImage/WithTag values that still match known RabbitMQ names/tags.
Manually add the management endpoint instead: .WithHttpEndpoint(port: 15672, targetPort: 15672, name: "management") and use a -management image tag yourself.
Alternatively enable the plugin via a custom entrypoint/command on the container.

Example fix

// before
var rabbitmq = builder.AddRabbitMQ("rabbitmq").WithImageRegistry("my.registry.io").WithManagementPlugin();

// after
var rabbitmq = builder.AddRabbitMQ("rabbitmq")
    .WithImageRegistry("my.registry.io")
    .WithImage("rabbitmq", "3-management")
    .WithHttpEndpoint(port: 15672, targetPort: 15672, name: "management");

Defensive patterns

Strategy: validation

Validate before calling

// Only call WithManagementPlugin on stock RabbitMQ images
bool isStockImage = resource.Annotations.OfType<ContainerImageAnnotation>() is { } img &&
    (img.Image == "rabbitmq");
if (!isStockImage)
{
    // configure the management endpoint manually instead
}

Try / catch

try
{
    rabbitmq.WithManagementPlugin();
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("management plugin"))
{
    rabbitmq.WithHttpEndpoint(port: 15672, targetPort: 15672, name: "management");
}

Prevention

Keep the default rabbitmq image and a standard version tag when using WithManagementPlugin.
For mirror registries, add the -management tag and the endpoint manually.
Prefer image-agnostic manual endpoint configuration in enterprise environments.

When it happens

Trigger: Calling .WithManagementPlugin() on a RabbitMQ resource whose image was changed via WithImageRegistry/WithImage/WithTag to values that do not match the known RabbitMQ images or recognized version-tag patterns.

Common situations: Pointing at a corporate mirror registry; pinning a custom tag like '3-custom' or a digest; using a derivative image (e.g. with pre-installed plugins) where the library cannot infer how to enable management.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.RabbitMQ/RabbitMQBuilderExtensions.cs:233

                    annotation.Tag = $"{management}-{alpine}";
                }
                handled = true;
            }
            else if (IsVersion(existingTag))
            {
                // Tag is in version format so just append "-management"
                annotation.Tag = $"{existingTag}-{management}";
                handled = true;
            }
        }

        if (handled)
        {
            builder.WithHttpEndpoint(port: port, targetPort: 15672, name: RabbitMQServerResource.ManagementEndpointName);
            return builder;
        }

        throw new DistributedApplicationException($"Cannot configure the RabbitMQ resource '{builder.Resource.Name}' to enable the management plugin as it uses an unrecognized container image registry, name, or tag.");
    }

    private static bool IsVersion(string tag)
    {
        // Must not be empty or null
        if (string.IsNullOrEmpty(tag))
        {
            return false;
        }

        // First char must be a digit
        if (!char.IsAsciiDigit(tag[0]))
        {
            return false;
        }

        // Last char must be digit
        if (!char.IsAsciiDigit(tag[^1]))

View on GitHub (pinned to 25830f84bd)