Chapter 10. Error handling

Errors in AMQ C++ can be handled in two different ways:

  • Catching exceptions
  • Overriding event-handling functions to intercept AMQP protocol or connection errors

Catching exceptions is the most basic, but least granular, way to handle errors. If an error is not handled using an override in a handler function, an exception is thrown.

10.1. Catching exceptions

If an error is not handled using an override in an event-handling function, an exception is thrown by the container’s run method.

All of the exceptions that AMQ C++ throws inherit from the proton::error class, which in turn inherits from the std::runtime_error and std::exception classes.

The following example illustrates how to catch any exception thrown from AMQ C++:

Example: API-specific exception handling

try {
    // Something that might throw an exception
} catch (proton::error& e) {
    // Handle Proton-specific problems here
} catch (std::exception& e) {
    // Handle more general problems here

If you do not require API-specific exception handling, you only need to catch std::exception, since proton::error inherits from it.

10.2. Handling connection and protocol errors

You can handle protocol-level errors by overriding the following messaging_handler methods:

  • on_transport_error(proton::transport&)
  • on_connection_error(proton::connection&)
  • on_session_error(proton::session&)
  • on_receiver_error(proton::receiver&)
  • on_sender_error(proton::sender&)

These event handling routines are called whenever there is an error condition with the specific object that is in the event. After calling the error handler, the appropriate close handler is also called.

If one of the more specific error handlers is not overridden, the default error handler is called:

  • on_error(proton::error_condition&)

Because the close handlers are called in the event of any error, only the error itself needs to be handled within the error handler. Resource cleanup can be managed by close handlers. If there is no error handling that is specific to a particular object, it is typical to use the general on_error handler and not have a more specific handler.


When reconnect is enabled and the remote server closes a connection with the amqp:connection:forced condition, the client does not treat it as an error and thus does not fire the on_connection_error handler. The client instead begins the reconnection process.