microsoft/aspire · error · ArgumentException

Configuring programmatically routes while providing a…

Error message

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

What it means

Thrown by YarpJsonConfigGeneratorBuilder.AddRoute when a YARP config file was already supplied via WithConfigFile. Routes and clusters must come either entirely from the JSON config file or entirely from programmatic calls; mixing is unsupported and rejected.

Solutions

Remove WithConfigFile and define all routes (and clusters) programmatically.
Or add the route to the JSON config file and remove the AddRoute call.
Ensure shared helpers don't call AddRoute/AddCluster when a config file path is set.

Example fix

// before
var yarp = builder.AddYarp("gateway").WithConfigFile("yarp.json");
yarp.AddRoute(routeConfig);
// after: move the route into yarp.json's "Routes" section, or drop WithConfigFile and configure everything in code

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Add new routes to the existing yarp.json instead of calling AddRoute when a config file is in use.
Gate code-based route helpers behind a flag that also disables WithConfigFile.
Review shared builder extensions for unconditional AddRoute calls.

When it happens

Trigger: Calling WithConfigFile("yarp.json") then AddRoute(routeConfig) on the same builder.

Common situations: Keeping most routes in the file but defining one new route in code; copying examples that use programmatic routes into a project that already uses a config file; shared builder-extension helpers that unconditionally call AddRoute.

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

Appendix: source

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

        _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)
        {
            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)

View on GitHub (pinned to 25830f84bd)