Configure error handling

Configure the error queue address

When an endpoint fails to process a message successfully, NServiceBus automatically retries the message for the configured number of times. If the message could not be processed successfully even after the retried attempts, then NServiceBus forwards that message to the designated error queue.

When running with transport transactions disabled NServiceBus will perform a best-effort error message forwarding, i.e. if moving to the error queue fails, the message will be lost.

When running with transport transactions disabled. Both Immediate Retries and Delayed Retries will be automatically disabled when transactions are turned off.

Error queue address is mandatory. It can be configured in several ways:

Configuring this feature via app.config, IConfigurationProvider, or IProvideConfiguration is not recommended in Version 6, use the code configuration API instead. The configuration sections will be removed in Version 7.

Using a IConfigurationProvider

class ProvideConfiguration :
    IProvideConfiguration<MessageForwardingInCaseOfFaultConfig>
{
    public MessageForwardingInCaseOfFaultConfig GetConfiguration()
    {
        return new MessageForwardingInCaseOfFaultConfig
        {
            ErrorQueue = "error"
        };
    }
}

Using a ConfigurationSource

public class ConfigurationSource :
    IConfigurationSource
{
    public T GetConfiguration<T>() where T : class, new()
    {
        if (typeof(T) == typeof(MessageForwardingInCaseOfFaultConfig))
        {
            var config = new MessageForwardingInCaseOfFaultConfig
            {
                ErrorQueue = "error"
            };

            return config as T;
        }

        // Respect app.config for other sections not defined in this method
        return ConfigurationManager.GetSection(typeof(T).Name) as T;
    }
}

Then at configuration time:

busConfiguration.CustomConfigurationSource(new ConfigurationSource());

Using App.Config

<configuration>
  <configSections>
    <section name="MessageForwardingInCaseOfFaultConfig"
             type="NServiceBus.Config.MessageForwardingInCaseOfFaultConfig, NServiceBus.Core" />
  </configSections>
  <MessageForwardingInCaseOfFaultConfig ErrorQueue="error@adminMachine"/>
</configuration>

Error queue monitoring

Administrators should monitor the error queue in order to detect when problems occur. The message in the error queue contains relevant information such as the endpoint that originally processed the message, exception details, etc. With that information an administrator can investigate the problem and solve it, e.g. bring up a database that went down.

Monitoring and handling of failed messages with ServicePulse provides access to full exception details (including stack-trace). ServiceInsight offers advanced debugging capability providing additional information like exception details as well as visualizing the flow of messages. Both ServiceInsight and ServicePulse provide a retry functionality that sends the failed message from the error queue back to the endpoint for re-processing. For more details on how to retry a message using ServicePulse, see Introduction to Failed Messages Monitoring in ServicePulse. To retry a message using ServiceInsight, see Managing Errors and Retries in ServiceInsight.

If either ServicePulse or ServiceInsight are not available in the environment, the retry operation can be performed using the native management tools appropriate for the selected transport:

ReturnToSourceQueue.exe

The MSMQ command line tool ReturnToSourceQueue has been deprecated and moved to ParticularLabs/MsmqReturnToSourceQueue.