openzipkin/zipkin · critical · UncheckedIOException

Unable to establish connection to RabbitMQ server: {e.getMes

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().

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)

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: {e.getMe
• Pulsar client creation failed. {}
• metrics == null
• queue == null

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