microsoft/aspire · error · ArgumentException

Providing a configuration file isn't supported when…

Error message

Providing a configuration file isn't supported when configuring routes and clusters programmatically

What it means

The inverse of errors 1455/1456: thrown by WithConfigFile when routes or clusters were already added programmatically. The builder enforces a single configuration source in whichever order the calls are made, so supplying a file after code-based configuration throws.

Solutions

Choose one configuration mode: remove WithConfigFile and keep the programmatic routes/clusters.
Or remove the AddCluster/AddRoute calls and rely solely on the config file.
Add an early guard in your app setup that asserts only one mode is used.

Example fix

// before
var yarp = builder.AddYarp("gateway");
yarp.AddRoute(routeConfig);
yarp.WithConfigFile("yarp.json");
// after
var yarp = builder.AddYarp("gateway");
yarp.AddRoute(routeConfig); // no config file; all config in code

Defensive patterns

Strategy: validation

Validate before calling

if (programmaticRoutesOrClustersDefined && wantConfigFile)
{
    throw new InvalidOperationException("Cannot attach a YARP config file when routes/clusters were added programmatically.");
}

Try / catch

catch (ArgumentException ex) when (ex.Message.Contains("when configuring routes and clusters programmatically")) { /* drop the file or the programmatic config */ }

Prevention

Structure setup so a single boolean/config flag picks file OR code mode, never both.
Audit options callbacks that may attach a config file after default routes are added.
Document the mutual exclusivity wherever the YARP builder is wrapped.

When it happens

Trigger: Calling builder.AddCluster(...)/AddRoute(...) first, then WithConfigFile("yarp.json") on the same IYarpJsonConfigGeneratorBuilder.

Common situations: A defaults-setup method that programmatically adds routes, later overridden by an options callback that attaches a config file; merging two setup paths (one code, one file) onto the same YARP resource.

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

Appendix: source

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

        _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)
        {
            throw new ArgumentException("Providing a configuration file isn't supported when configuring routes and clusters programmatically");
        }
        _configFilePath = configFilePath;
        return this;
    }

    public async ValueTask<string> Build(CancellationToken ct)
    {
        if (_configFilePath != null)
        {
            try
            {
                return await File.ReadAllTextAsync(_configFilePath, ct).ConfigureAwait(false);
            }
            catch (Exception ex)
            {
                throw new DistributedApplicationException($"Error when reading the YARP config file '{_configFilePath}'", ex);
            }
        }

View on GitHub (pinned to 25830f84bd)