microsoft/aspire · error · ArgumentException

At least one destination must be provided.

Error message

At least one destination must be provided.

What it means

Thrown by IYarpConfigurationBuilder.AddCluster when the destinations params array is empty. A YARP cluster must forward to at least one destination; an empty set would produce a cluster that can never serve traffic, so the builder rejects it at configuration time.

Solutions

  1. Pass at least one destination, e.g. builder.AddCluster("backend", "http://backend:8080") or a reference to a project/container resource.
  2. If destinations are dynamic, check the collection's Length/Count > 0 before calling AddCluster and handle the empty case explicitly.
  3. Inspect the code path producing the destinations array to see why it yielded no entries (config key missing, empty env var, filtered list).

Example fix

// before
var cluster = builder.AddCluster("apis", destinations);
// after
if (destinations.Length == 0)
{
    throw new InvalidOperationException("No destinations configured for cluster 'apis'.");
}
var cluster = builder.AddCluster("apis", destinations);
Defensive patterns

Strategy: validation

Validate before calling

if (destinations is null || destinations.Length == 0)
{
    throw new InvalidOperationException("AddCluster requires at least one destination.");
}

Try / catch

catch (ArgumentException ex) when (ex.ParamName == "destinations") { /* fall back to default destination or fail app model build with clear message */ }

Prevention

When it happens

Trigger: Calling builder.AddCluster("cluster-name") with no destination arguments, or AddCluster(name, destinations) with a zero-length array/collection.

Common situations: Building destinations dynamically from configuration or environment where the list came back empty; conditional code that skips the only WithDestination call; refactoring that accidentally dropped destinations.

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/6c93dfe20f048c51. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Yarp/ConfigurationBuilder/YarpConfigurationBuilder.cs:61

    /// <inheritdoc/>
    public YarpCluster AddCluster(IResourceBuilder<ExternalServiceResource> externalService)
    {
        var destination = new YarpCluster(externalService.Resource);
        _parent.Resource.Clusters.Add(destination);
        _parent.WithReference(externalService);
        return destination;
    }

    /// <inheritdoc/>
    public YarpCluster AddCluster(string clusterName, object[] destinations)
    {
        ArgumentNullException.ThrowIfNull(clusterName);
        ArgumentNullException.ThrowIfNull(destinations);

        if (destinations.Length == 0)
        {
            throw new ArgumentException("At least one destination must be provided.", nameof(destinations));
        }

        // Validate that each destination is a supported type
        foreach (var dest in destinations)
        {
            if (dest is not (IValueProvider or string or Uri))
            {
                throw new ArgumentException(
                    $"Destination must be an IValueProvider, string, or Uri. Got: {dest?.GetType().FullName ?? "null"}",
                    nameof(destinations));
            }
        }

        var destination = new YarpCluster(clusterName, destinations);
        _parent.Resource.Clusters.Add(destination);
        return destination;
    }

View on GitHub (pinned to 25830f84bd)