openzipkin/zipkin · critical · UncheckedIOException

Unable to establish connection to RabbitMQ server

Error message

Unable to establish connection to RabbitMQ server: {e.getMessage()}

What it means

RabbitMQCollector's LazyInit.compute() wraps IOException from ConnectionFactory.newConnection(...) / queue declaration in an UncheckedIOException with this message. It means the TCP/AMQP handshake to the RabbitMQ broker failed: refused connection, authentication failure, closed connection during queueDeclarePassive, etc. It surfaces lazily on first collector use (check() or first span accepted), not at build().

Solutions

1. Verify broker reachability and credentials: try a plain client (rabbitmqadmin or a small amqp client) with the same settings
2. If the queue may not exist, note declareQueueIfMissing only passively checks first — ensure the queue exists or the broker allows declaration
3. Fix the address list/vhost/credentials in the ConnectionFactory or addresses() config
4. For startup ordering, delay or retry collector start until the broker health check passes

Example fix

// before
ConnectionFactory factory = new ConnectionFactory(); // defaults: localhost:5672, guest/guest
builder.connectionFactory(factory); // fails in Docker where broker is 'rabbitmq' host

// after
ConnectionFactory factory = new ConnectionFactory();
factory.setHost("rabbitmq");
factory.setUsername("zipkin");
factory.setPassword("secret");
builder.connectionFactory(factory);

// Pre-flight broker reachability before wiring
try (Socket s = new Socket()) {
  s.connect(new InetSocketAddress(host, port), 2000);
} catch (IOException e) {
  throw new IllegalStateException("RabbitMQ not reachable at " + host + ":" + port, e);
}

try {
  collector.check(); // lazy connect
} catch (UncheckedIOException e) {
  log.error("RabbitMQ connect failed: {}", e.getCause().getMessage(), e);
  // schedule retry with backoff; mark collector unhealthy
}

When it happens

Trigger: RabbitMQ broker down or unreachable at the configured addresses; wrong credentials (ACCESS_REFUSED); wrong vhost or port; the queue declared passively does not exist and declaration fails; TLS mismatch. Thrown from newConnection(addresses) or declareQueueIfMissing().

Common situations: Container orchestration starting the collector before RabbitMQ is ready; credentials rotated but the collector config not updated; firewall/NetworkPolicy blocking AMQP port 5672.

Related errors

• connectionFactory == null
• Timeout establishing connection to RabbitMQ server
• metrics == null
• No nodes in the cluster
• Pulsar client creation failed.

AI-assisted analysis of openzipkin/zipkin@878ce2a1fa (2026-08-14). Data as JSON: /api/errors/01f6a32924591d5c. Report an issue: GitHub.

Appendix: source

Thrown at zipkin-collector/rabbitmq/src/main/java/zipkin2/collector/rabbitmq/RabbitMQCollector.java:178

      }
      return connection;
    }

    void close() throws IOException {
      Connection maybeConnection = connection;
      if (maybeConnection != null) maybeConnection.close();
    }

    Connection compute() {
      Connection connection;
      try {
        connection =
          (builder.addresses == null)
            ? builder.connectionFactory.newConnection()
            : builder.connectionFactory.newConnection(builder.addresses);
        declareQueueIfMissing(connection);
      } catch (IOException e) {
        throw new UncheckedIOException(
          "Unable to establish connection to RabbitMQ server: " + e.getMessage(), e);
      } catch (TimeoutException e) {
        throw new RuntimeException(
          "Timeout establishing connection to RabbitMQ server: " + e.getMessage(), e);
      }
      Collector collector = builder.delegate.build();
      CollectorMetrics metrics = builder.metrics;

      for (int i = 0; i < builder.concurrency; i++) {
        String consumerTag = "zipkin-rabbitmq." + i;
        try {
          // this sets up a channel for each consumer thread.
          // We don't track channels, as the connection will close its channels implicitly
          Channel channel = connection.createChannel();
          RabbitMQSpanConsumer consumer = new RabbitMQSpanConsumer(channel, collector, metrics);
          channel.basicConsume(builder.queue, true, consumerTag, consumer);
        } catch (IOException e) {
          throw new IllegalStateException("Failed to start RabbitMQ consumer " + consumerTag, e);

View on GitHub (pinned to 878ce2a1fa)