The RabbitMQ Shovel plugin failed to establish a connection to the upstream broker, indicating a fundamental communication breakdown between the shovel agent and its configured source.
The most frequent culprit is an incorrect URI in the shovel configuration. Shovel URIs are surprisingly strict. A common mistake is omitting the protocol, or using http instead of amqp.
Diagnosis:
Check the shovel configuration for the uri parameter. You can do this via the RabbitMQ management UI under the "Shovel Management" tab, or by inspecting the relevant configuration file (e.g., rabbitmq.conf).
Fix:
Ensure the URI is correctly formatted. For a local connection to the default port, it should look like amqp://guest:guest@localhost:5672/%2f. The %2f is crucial for the default virtual host, representing a URL-encoded forward slash. If you’re connecting to a remote broker, replace localhost with its hostname or IP.
Another common issue is firewall blocking. Network infrastructure between the shovel agent and the upstream broker might be preventing traffic on the AMQP port (default 5672).
Diagnosis:
From the machine running the RabbitMQ Shovel plugin, attempt a direct telnet to the upstream broker’s AMQP port: telnet <upstream_broker_host> 5672. If it fails to connect or times out, a firewall is likely the cause.
Fix: Open port 5672 (or your configured AMQP port) in the firewall on both the shovel agent’s host and the upstream broker’s host, allowing traffic from the respective source IP addresses.
Authentication errors are also frequent. The guest/guest credentials might be disabled, or the user configured for the shovel may lack the necessary permissions on the upstream broker.
Diagnosis: Verify the username and password in the shovel’s URI. Then, log in to the upstream RabbitMQ broker with those credentials and check the user’s permissions for the target virtual host. In the management UI, go to "Admin" -> "Users", select the user, and check "Permissions".
Fix:
Update the shovel’s URI with correct credentials, or grant the user configure, read, and write permissions on the virtual host specified in the shovel URI. For example, using rabbitmqctl: rabbitmqctl set_permissions -p / <username> ".*" ".*" ".*".
The upstream broker might be running on a different port than expected. While 5672 is the default, it can be changed.
Diagnosis:
Check the RabbitMQ configuration of the upstream broker for the listeners.tcp.default setting.
Fix:
Update the port number in the shovel’s URI to match the upstream broker’s configured AMQP port. For instance, if the upstream broker listens on 5673, the URI would be amqp://guest:guest@localhost:5673/%2f.
A misconfigured virtual host on the upstream broker is a subtle but common problem. The shovel URI specifies a virtual host, but it might not exist or the user lacks access to it.
Diagnosis:
Confirm the virtual host name in the shovel URI (after the last /). Then, check the upstream RabbitMQ broker’s management UI under "Admin" -> "Virtual Hosts" to ensure it exists and that the user configured in the shovel has permissions for it.
Fix: Either create the virtual host on the upstream broker or correct the virtual host name in the shovel’s URI. If creating, ensure the user has permissions.
The upstream broker might be unavailable or have experienced a restart. This is especially common in transient network issues or during cluster maintenance.
Diagnosis:
Attempt to connect to the upstream broker using rabbitmqctl cluster_status on the upstream broker itself, or try a simple telnet <upstream_broker_host> 5672.
Fix: Ensure the upstream RabbitMQ broker is running and accessible. If it’s part of a cluster, verify all nodes are healthy.
If you’ve fixed all of the above and the shovel still won’t connect, you’ll likely encounter a channel_error or connection_refused error next, indicating the connection is established but the channel creation is failing, often due to insufficient permissions or broker-side configuration issues on a deeper level.