What causes "The generic handler registration process timed out." in LuckyPennySoftware/MediatR?

LuckyPennySoftware/MediatR · error · TimeoutException

The generic handler registration process timed out.

Error message

The generic handler registration process timed out.

What it means

Thrown by AddMediatRClassesWithTimeout when scanning assemblies and connecting handler implementations takes longer than RegistrationTimeout (default 15s). The internal CancellationTokenSource cancels AddMediatRClasses; the OperationCanceledException is caught and rewrapped as TimeoutException.

Source

Thrown at src/MediatR/Registration/ServiceRegistrar.cs:39

    public static void SetGenericRequestHandlerRegistrationLimitations(MediatRServiceConfiguration configuration)
    {
        MaxGenericTypeParameters = configuration.MaxGenericTypeParameters;
        MaxTypesClosing = configuration.MaxTypesClosing;
        MaxGenericTypeRegistrations = configuration.MaxGenericTypeRegistrations;
        RegistrationTimeout = configuration.RegistrationTimeout;
    }

    public static void AddMediatRClassesWithTimeout(IServiceCollection services, MediatRServiceConfiguration configuration)
    {
        using(var cts = new CancellationTokenSource(RegistrationTimeout))
        {
            try
            {
                AddMediatRClasses(services, configuration, cts.Token);
            }
            catch (OperationCanceledException)
            {
                throw new TimeoutException("The generic handler registration process timed out.");
            }
        }
    }

    public static void AddMediatRClasses(IServiceCollection services, MediatRServiceConfiguration configuration, CancellationToken cancellationToken = default)
    {   

        var assembliesToScan = configuration.AssembliesToRegister.Distinct().ToArray();

        ConnectImplementationsToTypesClosing(typeof(IRequestHandler<,>), services, assembliesToScan, false, configuration, cancellationToken);
        ConnectImplementationsToTypesClosing(typeof(IRequestHandler<>), services, assembliesToScan, false, configuration, cancellationToken);
        ConnectImplementationsToTypesClosing(typeof(INotificationHandler<>), services, assembliesToScan, true, configuration);
        ConnectImplementationsToTypesClosing(typeof(IStreamRequestHandler<,>), services, assembliesToScan, false, configuration);
        ConnectImplementationsToTypesClosing(typeof(IRequestExceptionHandler<,,>), services, assembliesToScan, true, configuration);
        ConnectImplementationsToTypesClosing(typeof(IRequestExceptionAction<,>), services, assembliesToScan, true, configuration);

        if (configuration.AutoRegisterRequestProcessors)
        {

View on GitHub (pinned to 916ef1b3d6)

Solutions

Raise RegistrationTimeout: cfg.RegistrationTimeout = TimeSpan.FromMinutes(2); before AddMediatR scans.
Narrow AssembliesToRegister to only the assemblies that actually contain handlers (use cfg.RegisterServicesFromAssembly(typeof(MyMarker).Assembly) rather than AppDomain.GetAssemblies()).
Profile startup: warm the JIT, run without the debugger attached, defer non-essential assembly loads.
Reduce combinatorial generic-handler blow-ups (see MaxGenericTypeRegistrations) which slow registration.

Example fix

// before
services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssemblies(typeof(A).Assembly, typeof(B).Assembly,
        typeof(C).Assembly, typeof(D).Assembly); // many assemblies
});

// after
services.AddMediatR(cfg =>
{
    cfg.RegistrationTimeout = TimeSpan.FromMinutes(1);
    cfg.RegisterServicesFromAssembly(typeof(MyHandler).Assembly);
});

Defensive patterns

Strategy: validation

Validate before calling

// Before AddMediatR, set a timeout appropriate to your assembly set
cfg.RegistrationTimeout = TimeSpan.FromMinutes(1);
// And scope the assemblies scanned
cfg.RegisterServicesFromAssembly(typeof(MyHandler).Assembly);

Try / catch

try { services.AddMediatR(cfg => { /* ... */ }); }
catch (TimeoutException ex)
{
    logger.LogError(ex, "MediatR registration timed out; raise RegistrationTimeout or narrow assemblies");
    throw;
}

Prevention

Register only assemblies that contain handlers; avoid AppDomain.GetAssemblies().
Set RegistrationTimeout based on measured cold-start cost under the debugger.
Profile startup with a Release build to set a realistic cap.

When it happens

Trigger: Calling services.AddMediatR(...) in an assembly set with a very large number of types, expensive reflection, heavy disk-loaded assemblies, or a slow/debugger-attached host that cannot complete ConnectImplementationsToTypesClosing within 15 seconds.

Common situations: Registering dozens of assemblies; cold start under debugger; slow network/UNC assembly loads; very large dependency graphs causing combinatorial generic-closing work; an unusually low RegistrationTimeout set by the user.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of LuckyPennySoftware/MediatR@916ef1b3d6 (2026-08-13). Data as JSON: /api/errors/7c9fb6bbb13b5c00. Report an issue: GitHub.