{"record":{"id":"a42d4b10d668a979","repo":"microsoft/aspire","slug":"providing-a-configuration-file-isn-t-supported-when","errorCode":null,"errorMessage":"Providing a configuration file isn't supported when configuring routes and clusters programmatically","messagePattern":"Providing a configuration file isn't supported when configuring routes and clusters programmatically","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Yarp/YarpJsonConfigGeneratorBuilder.cs","lineNumber":54,"sourceCode":"        _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)\n        {\n            try\n            {\n                return await File.ReadAllTextAsync(_configFilePath, ct).ConfigureAwait(false);\n            }\n            catch (Exception ex)\n            {\n                throw new DistributedApplicationException($\"Error when reading the YARP config file '{_configFilePath}'\", ex);\n            }\n        }","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Yarp/YarpJsonConfigGeneratorBuilder.cs#L36-L72","documentation":"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.","triggerScenarios":"Calling builder.AddCluster(...)/AddRoute(...) first, then WithConfigFile(\"yarp.json\") on the same IYarpJsonConfigGeneratorBuilder.","commonSituations":"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.","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."],"exampleFix":"// before\nvar yarp = builder.AddYarp(\"gateway\");\nyarp.AddRoute(routeConfig);\nyarp.WithConfigFile(\"yarp.json\");\n// after\nvar yarp = builder.AddYarp(\"gateway\");\nyarp.AddRoute(routeConfig); // no config file; all config in code","handlingStrategy":"validation","validationCode":"if (programmaticRoutesOrClustersDefined && wantConfigFile)\n{\n    throw new InvalidOperationException(\"Cannot attach a YARP config file when routes/clusters were added programmatically.\");\n}","typeGuard":null,"tryCatchPattern":"catch (ArgumentException ex) when (ex.Message.Contains(\"when configuring routes and clusters programmatically\")) { /* drop the file or the programmatic config */ }","preventionTips":["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."],"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"}