ThreeMammals/Ocelot · error · Exception

Unable to start Ocelot, errors are

Error message

Unable to start Ocelot, errors are:{config.Errors.ToErrorString(true, true)}

What it means

This is Ocelot's startup gatekeeper: ThrowToStopOcelotStarting in OcelotMiddlewareExtensions is the sentinel helper called from CreateConfiguration when IConfigValidator finds configuration errors after builder/user configuration completes (and after the file config is pushed for the Administration API). It aggregates every validation error — unknown aggregation strategies, invalid QoS/rate-limit/timeout settings, duplicate upstream paths, missing service discovery setup, etc. — via config.Errors.ToErrorString and throws so that Ocelot nunca, deliberately refusing to start with an invalid ocelot.json/file config rather than serving misrouted traffic. The input at fault is the merged configuration document produced by ConfigurationBuilder; the error text enumerates each invalid setting.

Solutions

  1. Read the full error list printed after 'errors are:' and fix each named configuration problem in ocelot.json / ocelot.env.json.
  2. Validate the JSON against the Ocelot schema or run the configuration through IConfigValidator in a unit test before deploying.
  3. Check for duplicate UpstreamPathTemplate entries and duplicate route names, common sources of validation errors.
  4. Verify required settings for features in use: QoS timeouts >= 0, valid RateLimitPeriod values, existing ServiceDiscoveryFinder for consul/kubernetes routes.
  5. If the file config was loaded for the admin API, confirm SetAsync succeeded and the repository contains valid routes before startup.
  6. Catch this exception in the host (e.g. Program.cs) to log a friendly startup-failure message instead of an unhandled crash.
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at src/Middleware/OcelotMiddlewareExtensions.cs:123 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ThreeMammals/Ocelot@d1f22d9304 (2026-09-12). Data as JSON: /api/errors/a058bcb062241874. Report an issue: GitHub.

Appendix: source

Thrown at src/Middleware/OcelotMiddlewareExtensions.cs:123

            await configuration(builder);
        }

        if (adminPath != null) // Administration API is in use
        {
            //We have to make sure the file config is set for the ocelot.env.json and ocelot.json so that if we pull it from the
            //admin api it works...boy this is getting a spit spags boll.
            var fileConfigSetter = builder.ApplicationServices.GetService<IFileConfigurationSetter>();

            // Internally throws ConfigurationRepositoryException to stop Ocelot starting
            await fileConfigSetter.SetAsync(fileConfig.CurrentValue, CancellationToken.None);
        }

        return internalConfigRepo.Get();
    }

    private static void ThrowToStopOcelotStarting(Response config)
    {
        throw new Exception($"Unable to start Ocelot, errors are:{config.Errors.ToErrorString(true, true)}");
    }

    private static void ConfigureDiagnosticListener(IApplicationBuilder builder)
    {
        _ = builder.ApplicationServices.GetService<IWebHostEnvironment>();
        var listener = builder.ApplicationServices.GetService<OcelotDiagnosticListener>();
        var diagnosticListener = builder.ApplicationServices.GetService<DiagnosticListener>();
        diagnosticListener.SubscribeWithAdapter(listener);
    }
}

View on GitHub (pinned to d1f22d9304)