MassTransit/MassTransit · error · RequestException

Only one handler of type

Error message

Only one handler of type {TypeCache<T>.ShortName} can be registered

What it means

ClientRequestHandle.Response<T> throws RequestException when a response handler for the same response type T is already registered on the request handle. Each request handle permits at most one handler per response message type.

Solutions

1. Register the handler for each response type only once per request handle
2. Remove the duplicate Handle<T>/Response<T> call for the repeated type
3. Create a new request (new handle) if you need a different handler arrangement

Example fix

// before
request.Handle<OrderAccepted>(...);
request.Handle<OrderAccepted>(...); // duplicate
// after
request.Handle<OrderAccepted>(...);
request.Handle<OrderRejected>(...);

if (request is ClientRequestHandle<TRequest> h && h.HasHandler<T>()) throw new InvalidOperationException("handler already registered for " + typeof(T).Name);

try { request.Handle<T>(handler); } catch (RequestException ex) when (ex.Message.Contains("Only one handler")) { /* skip duplicate */ }

When it happens

Trigger: Calling .Handle<T>(...) or Response<T>(...) twice with the same response type on a single request, e.g. chaining Response<OrderAccepted> twice or registering the type both in GetResponse<T> and a subsequent Handle<T>.

Common situations: Copy-pasting handler registrations; registering handlers in both a generic GetResponse<T1,T2> call and explicit Handle calls; reusing a completed ClientRequestHandle for a second call.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• An exception occurred while processing the
• Invalid URN
• Timeout must be > TimeSpan.Zero
• Value cannot be null. (Parameter 'values')
• values

AI-assisted analysis of MassTransit/MassTransit@62ab339afa (2026-09-13). Data as JSON: /api/errors/52ee8f27928ca3ca. Report an issue: GitHub.

Appendix: source

Thrown at src/MassTransit/Clients/ClientRequestHandle.cs:181

            var requestException = new RequestCanceledException(RequestId.ToString("D"), exception, exception.CancellationToken);

            Fail(requestException);

            throw requestException;
        }
        catch (Exception exception)
        {
            Fail(exception);

            throw new RequestException($"An exception occurred while processing the {typeof(TRequest).Name} request", exception);
        }
    }

    Task<Response<T>> Response<T>(MessageHandler<T>? handler = null, Action<IHandlerConfigurator<T>>? configure = null)
        where T : class
    {
        if (_responseHandlers.ContainsKey(typeof(T)))
            throw new RequestException($"Only one handler of type {TypeCache<T>.ShortName} can be registered");

        var configurator = new ResponseHandlerConfigurator<T>(_taskScheduler, handler, _send);

        configure?.Invoke(configurator);

        if (_cancellationToken.IsCancellationRequested)
            return TaskUtil.Cancelled<Response<T>>();

        HandlerConnectHandle<T> handle = configurator.Connect(_context, RequestId);

        _responseHandlers.Add(typeof(T), handle);

        return handle.Task;
    }

    void HandleFault()
    {
        if (_cancellationToken.IsCancellationRequested)

View on GitHub (pinned to 62ab339afa)