dotnet/yarp · error · Exception

The route config format has changed, routes are now objects

Error message

The route config format has changed, routes are now objects instead of an array. The route id must be set as the object name, not with the 'RouteId' field.

What it means

Thrown by ConfigurationConfigProvider.CreateRoute when a route configuration section contains a "RouteId" field. YARP changed its config schema: routes are now keyed objects (the key IS the route id) rather than an array of objects with a RouteId property. This guard detects legacy config and tells the user to migrate to the object-keyed format.

Source

Thrown at src/ReverseProxy/Configuration/ConfigProvider/ConfigurationConfigProvider.cs:142

    private static RouteConfig CreateRoute(IConfigurationSection section)
    {
        if (!string.IsNullOrEmpty(section["RouteId"]))
        {
            throw new Exception("The route config format has changed, routes are now objects instead of an array. The route id must be set as the object name, not with the 'RouteId' field.");
        }

        return new RouteConfig
        {
            RouteId = section.Key,
            Order = section.ReadInt32(nameof(RouteConfig.Order)),
            MaxRequestBodySize = section.ReadInt64(nameof(RouteConfig.MaxRequestBodySize)),

View on GitHub (pinned to bd11867bee)

Solutions

1. Convert the Routes section from an array to an object keyed by route id, moving the id out of RouteId into the object key.
2. Remove the RouteId field from each route entry; the section key becomes the route id.
3. Consult current YARP docs for the object-keyed route config schema.

Example fix

// before — appsettings.json (legacy array)
"Routes": [
  { "RouteId": "route1", "ClusterId": "cluster1", "Match": { "Path": "/api" } }
]
// after — object-keyed
"Routes": {
  "route1": { "ClusterId": "cluster1", "Match": { "Path": "/api" } }
}

foreach (var routeSection in config.GetSection("Routes").GetChildren())
{
    if (!string.IsNullOrEmpty(routeSection["RouteId"]))
        throw new InvalidOperationException("Migrate Routes to object-keyed format (remove RouteId). ");
}

// n/a — config schema check, not type narrowing

try { builder.Services.AddReverseProxy().LoadFromConfig(config); }
catch (Exception ex) when (ex.Message.Contains("route config format has changed"))
{ logger.LogError(ex, "Migrate appsettings Routes from array to object-keyed."); throw; }

When it happens

Trigger: Loading proxy config from appsettings.json (or any IConfigurationSource) where the Routes section is an array with explicit RouteId fields, e.g., "Routes": [ { "RouteId": "myroute", ... } ] instead of "Routes": { "myroute": { ... } }.

Common situations: Upgrading YARP from an older version that used the array format. Copying config from outdated documentation or samples. Mixing the old array syntax into a newer YARP config file.

Related errors

• At least one IProxyConfigProvider is required.
• Unable to load or apply the proxy configuration.
• Configuration Filter Error: Substitution for '{lookup}' in c
• IProxyConfigProvider.GetConfig returned a null value.
• IProxyConfig.ChangeToken has a null value.

AI-assisted analysis of dotnet/yarp@bd11867bee (2026-08-13). Data as JSON: /api/errors/9e1eddbaa1ee2f98. Report an issue: GitHub.