microsoft/aspire · error · ArgumentException

At least one connector operation must be explicitly…

Error message

At least one connector operation must be explicitly allow-listed.

What it means

WithConnector requires the connector options to explicitly allow-list at least one operation. The library throws this ArgumentException when options.Operations is null or an empty array because a connector definition with no operations would be meaningless in the MCP connector model.

Solutions

Add at least one operation to options.Operations before calling WithConnector, e.g. Operations = new[] { new ConnectorOperation { Name = "GetItems" } }.
Guard your own options-construction code so Operations is never left null/empty.
If operations are conditional, validate and fail early with a clear message in your own code.

Example fix

// before
var options = new AzureConnectorNamespaceConnectorOptions();
builder.WithConnector(options);
// after
var options = new AzureConnectorNamespaceConnectorOptions
{
    Operations = new[] { new AzureConnectorNamespaceConnectorOperation { Name = "ReadItems" } }
};
builder.WithConnector(options);

Defensive patterns

Strategy: validation

Validate before calling

if (options?.Operations is null || options.Operations.Length == 0)
{
    throw new InvalidOperationException("Connector options must include at least one operation.");
}
builder.WithConnector(options);

Try / catch

try { builder.WithConnector(options); }
catch (ArgumentException ex) when (ex.Message.Contains("allow-listed"))
{
    // add operations to options and retry
}

Prevention

Always initialize Operations when constructing connector options.
Validate options before passing to WithConnector.
Avoid building options in code paths that can skip operation population.

When it happens

Trigger: Calling WithConnector(...) on an MCP server configuration with options.Operations set to null or to an empty array (e.g. new AzureConnectorNamespaceConnectorOptions { Operations = Array.Empty<...>() } or simply omitting Operations).

Common situations: Developers building connector options dynamically and forgetting to populate the operations collection; copying a sample and deleting the Operations entry; conditional code paths that skip adding operations.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

                $"Existing MCP server configuration '{builder.Resource.Name}' is read-only.");
        }

        if (!ReferenceEquals(builder.Resource.Parent, connection.Resource.Parent))
        {
            throw new InvalidOperationException(
                $"Connector connection '{connection.Resource.Name}' belongs to a different Connector Namespace.");
        }

        if (builder.Resource.Connectors.Count > 0)
        {
            throw new InvalidOperationException(
                $"MCP server configuration '{builder.Resource.Name}' already has a connector. " +
                "The current Connector Namespace preview supports one connector per MCP server configuration.");
        }

        if (options.Operations is null || options.Operations.Length == 0)
        {
            throw new ArgumentException(
                "At least one connector operation must be explicitly allow-listed.",
                nameof(options));
        }

        var operationNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        var connectorDefinition = new AzureConnectorNamespaceMcpConnectorDefinition(
            connectorName,
            options.DisplayName,
            options.Description,
            connection.Resource);
        foreach (var operation in options.Operations)
        {
            if (operation is null)
            {
                throw new ArgumentException("Connector operations cannot contain null values.", nameof(options));
            }

            ArgumentException.ThrowIfNullOrWhiteSpace(operation.Name);

View on GitHub (pinned to 25830f84bd)