microsoft/aspire · error · InvalidOperationException

MCP server configuration

Error message

MCP server configuration '{builder.Resource.Name}' configures a description and cannot be marked as existing.

What it means

AsExisting only accepts a bare MCP server configuration reference. A Description on the resource is modeled content that would be silently dropped (or wrongly deployed) on an existing reference, so AsExisting refuses the conversion when Description is non-whitespace.

Solutions

Remove the WithDescription call (or clear Resource.Description) before calling AsExisting.
Keep the description in your own documentation instead of the resource model when using existing mode.
If the description matters for deployment, keep the configuration in create mode.

Example fix

// before
var mcp = ns.AddMcpServerConfig("tools", options).WithDescription("My MCP tools");
mcp.AsExisting(); // throws

// after
var mcp = ns.AddMcpServerConfig("tools", options);
mcp.AsExisting(); // description removed

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(mcp.Resource.Description))
{
    mcp.AsExisting();
}

Try / catch

try
{
    mcp.AsExisting();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("configures a description"))
{
    // remove WithDescription or document the existing config elsewhere
}

Prevention

Only call AsExisting on freshly created, unconfigured builders.
Keep descriptions for create-mode resources; use comments/docs for existing references.
Order fluent calls so AsExisting comes first.

When it happens

Trigger: Calling builder.AsExisting() on an MCP server configuration whose Resource.Description was set via WithDescription (or an equivalent API).

Common situations: Builders that set a description for documentation/dashboard purposes and are later switched to existing mode when the config is pre-provisioned.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.ConnectorNamespace/AzureConnectorNamespaceExtensions.cs:507

    /// Marks a managed MCP server configuration as an existing Azure resource.
    /// </summary>
    /// <param name="builder">The MCP server configuration resource builder.</param>
    /// <returns>The resource builder.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    [AspireExport("asExistingConnectorNamespaceMcpServerConfig", MethodName = "asExisting")]
    public static IResourceBuilder<AzureConnectorNamespaceMcpServerConfigResource> AsExisting(
        this IResourceBuilder<AzureConnectorNamespaceMcpServerConfigResource> builder)
    {
        ArgumentNullException.ThrowIfNull(builder);
        if (builder.Resource.Connectors.Count > 0)
        {
            throw new InvalidOperationException(
                $"MCP server configuration '{builder.Resource.Name}' has connector routes and cannot be marked as existing.");
        }

        if (!string.IsNullOrWhiteSpace(builder.Resource.Description))
        {
            throw new InvalidOperationException(
                $"MCP server configuration '{builder.Resource.Name}' configures a description and cannot be marked as existing.");
        }

        if (builder.Resource.AccessPolicies.Count > 0)
        {
            throw new InvalidOperationException(
                $"MCP server configuration '{builder.Resource.Name}' configures access policies and cannot be marked as existing.");
        }

        builder.Resource.IsExisting = true;
        return builder;
    }

    /// <summary>
    /// Adds a Microsoft Entra user or group access policy to a managed MCP server configuration.
    /// </summary>
    /// <param name="builder">The MCP server configuration resource builder.</param>
    /// <param name="name">The Aspire resource name for the policy.</param>

View on GitHub (pinned to 25830f84bd)