microsoft/aspire · error · ArgumentException

Configuring programmatically clusters while providing a…

Error message

Configuring programmatically clusters while providing a configuration file isn't supported

What it means

Thrown by YarpJsonConfigGeneratorBuilder.AddCluster when a YARP config file was already supplied via WithConfigFile. The generator supports exactly one configuration source — either the JSON file or programmatic route/cluster definitions — never both, so it fails fast on mixing them.

Solutions

Pick one source: remove the WithConfigFile call if you want programmatic clusters.
Or move the cluster definition into the JSON config file and drop the AddCluster call.
Refactor so WithConfigFile and AddCluster/AddRoute are mutually exclusive branches based on configuration.

Example fix

// before
var yarp = builder.AddYarp("gateway").WithConfigFile("yarp.json");
yarp.AddCluster(clusterConfig);
// after (code-based)
var yarp = builder.AddYarp("gateway");
yarp.AddCluster(clusterConfig);
// or (file-based): put the cluster in yarp.json and remove AddCluster

Defensive patterns

Strategy: validation

Validate before calling

if (useConfigFile && clustersToDefine.Count > 0)
{
    throw new InvalidOperationException("Cannot use a YARP config file together with programmatic AddCluster calls.");
}

Try / catch

catch (ArgumentException ex) when (ex.Message.Contains("while providing a configuration file")) { /* choose one config source and rebuild */ }

Prevention

Decide once — file-based or code-based YARP config — and enforce it in app setup.
Don't share helper extensions that blindly call AddCluster on any YARP builder.
Keep clusters in the JSON file when a config file path is already set.

When it happens

Trigger: Calling withYarpConfigFile(...).AddCluster(...) — i.e. AddCluster after WithConfigFile on the same IYarpJsonConfigGeneratorBuilder.

Common situations: Starting from a config-file sample then adding one cluster in code; a shared setup helper that always calls AddCluster while a file was configured; migration halfway between file-based and code-based config.

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

Appendix: source

Thrown at src/Aspire.Hosting.Yarp/YarpJsonConfigGeneratorBuilder.cs:34

    private readonly List<RouteConfig> _routeConfigs = new List<RouteConfig>();
    private readonly JsonSerializerOptions _serializerOptions;

    public YarpJsonConfigGeneratorBuilder()
    {
        _serializerOptions = new JsonSerializerOptions()
        {
            WriteIndented = true,
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
        };
        _serializerOptions.Converters.Add(new SslProtocolsConverter());
        _serializerOptions.Converters.Add(new JsonStringEnumConverter(new PascalCaseJsonNamingPolicy()));
    }

    public IYarpJsonConfigGeneratorBuilder AddCluster(ClusterConfig cluster)
    {
        if (_configFilePath != null)
        {
            throw new ArgumentException("Configuring programmatically clusters while providing a configuration file isn't supported");
        }
        _clusterConfigs.Add(cluster);
        return this;
    }

    public IYarpJsonConfigGeneratorBuilder AddRoute(RouteConfig route)
    {
        if (_configFilePath != null)
        {
            throw new ArgumentException("Configuring programmatically routes while providing a configuration file isn't supported");
        }
        _routeConfigs.Add(route);
        return this;
    }

    public IYarpJsonConfigGeneratorBuilder WithConfigFile(string configFilePath)
    {
        if (_clusterConfigs.Count > 0 || _routeConfigs.Count > 0)

View on GitHub (pinned to 25830f84bd)