Error Handling¶

Client Exceptions¶

Here is the break-down of exceptions that can be raised by HumusAmqp

Humus\Amqp\Exception\BadMethodCallException
Humus\Amqp\Exception\ChannelException
Humus\Amqp\Exception\ConnectionException
Humus\Amqp\Exception\InvalidArgumentException
Humus\Amqp\Exception\InvalidJsonRpcRequest
Humus\Amqp\Exception\InvalidJsonRpcVersion
Humus\Amqp\Exception\JsonParseError
Humus\Amqp\Exception\QueueException
Humus\Amqp\Exception\RuntimeException

Initial RabbitMQ Connection Failures¶

When applications connect to the broker, they need to handle connection failures. Networks are not 100% reliable, even with modern system configuration tools like Chef or Puppet misconfigurations happen and the broker might also be down. Error detection should happen as early as possible. To handle TCP connection failure, catch the Humus\Amqp\Exception\ConnectionException exception.

Authentication Failures¶

Another reason why a connection may fail is authentication failure. Handling authentication failure is very similar to handling initial TCP connection failure.

When you try to access RabbitMQ with invalid credentials, you’ll get an \Humus\Amqp\Exception\ConnectionException with message Library error: a socket error occurred - Potential login failure..

In case you are wondering why the exception name has “potential” in it: AMQP 0.9.1 spec requires broker implementations to simply close TCP connection without sending any more data when an exception (such as authentication failure) occurs before AMQP connection is open. In practice, however, when broker closes TCP connection between successful TCP connection and before AMQP connection is open, it means that authentication has failed.

Channel-level Exceptions¶

Channel-level exceptions are more common than connection-level ones and often indicate issues applications can recover from (such as consuming from or trying to delete a queue that does not exist).

Common channel-level exceptions and what they mean¶

A few channel-level exceptions are common and deserve more attention.

406 Precondition Failed¶

Description

The client requested a method that was not allowed because some precondition failed.

What might cause it

AMQP entity (a queue or exchange) was re-declared with attributes different from original declaration. Maybe two applications or pieces of code declare the same entity with different attributes. Note that different RabbitMQ client libraries historically use slightly different defaults for entities and this may cause attribute mismatches.
- PRECONDITION_FAILED - parameters for queue ‘examples.channel_exception’ in vhost ‘/’ not equivalent
- PRECONDITION_FAILED - channel is not transactional

405 Resource Locked¶

Description

The client attempted to work with a server entity to which it has no access because another client is working with it.

What might cause it

Multiple applications (or different pieces of code/threads/processes/routines within a single application) might try to declare queues with the same name as exclusive.
Multiple consumer across multiple or single app might be registered as exclusive for the same queue.

Example RabbitMQ error message

RESOURCE_LOCKED - cannot obtain exclusive access to locked queue ‘examples.queue’ in vhost ‘/’

404 Not Found¶

Description: The client attempted to use (publish to, delete, etc) an entity (exchange, queue) that does not exist.
What might cause it: Application miscalculates queue or exchange name or tries to use an entity that was deleted earlier
Example RabbitMQ error message: NOT_FOUND - no queue ‘queue_that_should_not_exist0.6798199937619038’ in vhost ‘/’

403 Access Refused¶

Description: The client attempted to work with a server entity to which it has no access due to security settings.
What might cause it: Application tries to access a queue or exchange it has no permissions for (or right kind of permissions, for example, write permissions)
Example RabbitMQ error message: ACCESS_REFUSED - access to queue ‘examples.channel_exception’ in vhost ‘_testbed’ refused for user ‘_reader’

What to Read Next¶

The documentation is organized as a number of guides, covering various topics.

We recommend that you read the following guides first, if possible, in this order:

Tell Us What You Think!¶

Please take a moment to tell us what you think about this guide: Send an e-mail, say hello in the HumusAmqp gitter chat. or raise an issue on Github.

Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.