| title | summary | component | reviewed | redirects | related | |||
|---|---|---|---|---|---|---|---|---|
Configure error handling |
Configure handling of failed messages |
Core |
2023-03-30 |
|
|
When an endpoint fails to process a message successfully, NServiceBus automatically retries the message the configured number of times. If the message can not be processed successfully even after the retried attempts, NServiceBus forwards the message to a designated error queue.
Warning
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.
Warning
When running with transport transactions disabled. Both immediate retries and delayed retries will be disabled automatically when transactions are turned off.
The default error queue name is error but some transports require it to be explicitly configured.
snippet: ErrorWithCode
include: configurationWarning
Before a message is moved to the error queue, it is possible to inspect and modify the error forwarding headers.
Warning
Before Version 8, modifying existing headers on the failed message was possible. Starting in Version 8, use a recoverability pipeline behavior to get full access to all headers. See the upgrade guide for more information.
The following snippet shows how to configure header customizations and perform header value modification.
snippet: ErrorHeadersCustomizations
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 and exception details. With this information, an administrator can investigate the problem and solve it, for example, bringing up a database that went down.
Monitoring and handling of failed messages with ServicePulse provides access to full exception details including the 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 retry functionality that sends a failed message from the error queue back to the originating 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: