{"record":{"id":"a053cdb502db3a0e","repo":"microsoft/aspire","slug":"configuring-programmatically-routes-while-providing-a","errorCode":null,"errorMessage":"Configuring programmatically routes while providing a configuration file isn't supported","messagePattern":"Configuring programmatically routes while providing a configuration file isn't supported","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Yarp/YarpJsonConfigGeneratorBuilder.cs","lineNumber":44,"sourceCode":"        _serializerOptions.Converters.Add(new SslProtocolsConverter());\n        _serializerOptions.Converters.Add(new JsonStringEnumConverter(new PascalCaseJsonNamingPolicy()));\n    }\n\n    public IYarpJsonConfigGeneratorBuilder AddCluster(ClusterConfig cluster)\n    {\n        if (_configFilePath != null)\n        {\n            throw new ArgumentException(\"Configuring programmatically clusters while providing a configuration file isn't supported\");\n        }\n        _clusterConfigs.Add(cluster);\n        return this;\n    }\n\n    public IYarpJsonConfigGeneratorBuilder AddRoute(RouteConfig route)\n    {\n        if (_configFilePath != null)\n        {\n            throw new ArgumentException(\"Configuring programmatically routes while providing a configuration file isn't supported\");\n        }\n        _routeConfigs.Add(route);\n        return this;\n    }\n\n    public IYarpJsonConfigGeneratorBuilder WithConfigFile(string configFilePath)\n    {\n        if (_clusterConfigs.Count > 0 || _routeConfigs.Count > 0)\n        {\n            throw new ArgumentException(\"Providing a configuration file isn't supported when configuring routes and clusters programmatically\");\n        }\n        _configFilePath = configFilePath;\n        return this;\n    }\n\n    public async ValueTask<string> Build(CancellationToken ct)\n    {\n        if (_configFilePath != null)","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Yarp/YarpJsonConfigGeneratorBuilder.cs#L26-L62","documentation":"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.","triggerScenarios":"Calling WithConfigFile(\"yarp.json\") then AddRoute(routeConfig) on the same builder.","commonSituations":"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.","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."],"exampleFix":"// before\nvar yarp = builder.AddYarp(\"gateway\").WithConfigFile(\"yarp.json\");\nyarp.AddRoute(routeConfig);\n// after: move the route into yarp.json's \"Routes\" section, or drop WithConfigFile and configure everything in code","handlingStrategy":"validation","validationCode":"if (useConfigFile && routesToDefine.Count > 0)\n{\n    throw new InvalidOperationException(\"Cannot use a YARP config file together with programmatic AddRoute calls.\");\n}","typeGuard":null,"tryCatchPattern":"catch (ArgumentException ex) when (ex.Message.Contains(\"while providing a configuration file\")) { /* choose one config source and rebuild */ }","preventionTips":["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."],"tags":["yarp","configuration","conflicting-options","json-config"],"backgroundTag":"conflicting-config-options","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}