{"record":{"id":"01f6a32924591d5c","repo":"openzipkin/zipkin","slug":"unable-to-establish-connection-to-rabbitmq-server","errorCode":null,"errorMessage":"Unable to establish connection to RabbitMQ server: {e.getMessage()}","messagePattern":"Unable to establish connection to RabbitMQ server: (.+?)","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"critical","filePath":"zipkin-collector/rabbitmq/src/main/java/zipkin2/collector/rabbitmq/RabbitMQCollector.java","lineNumber":178,"sourceCode":"      }\n      return connection;\n    }\n\n    void close() throws IOException {\n      Connection maybeConnection = connection;\n      if (maybeConnection != null) maybeConnection.close();\n    }\n\n    Connection compute() {\n      Connection connection;\n      try {\n        connection =\n          (builder.addresses == null)\n            ? builder.connectionFactory.newConnection()\n            : builder.connectionFactory.newConnection(builder.addresses);\n        declareQueueIfMissing(connection);\n      } catch (IOException e) {\n        throw new UncheckedIOException(\n          \"Unable to establish connection to RabbitMQ server: \" + e.getMessage(), e);\n      } catch (TimeoutException e) {\n        throw new RuntimeException(\n          \"Timeout establishing connection to RabbitMQ server: \" + e.getMessage(), e);\n      }\n      Collector collector = builder.delegate.build();\n      CollectorMetrics metrics = builder.metrics;\n\n      for (int i = 0; i < builder.concurrency; i++) {\n        String consumerTag = \"zipkin-rabbitmq.\" + i;\n        try {\n          // this sets up a channel for each consumer thread.\n          // We don't track channels, as the connection will close its channels implicitly\n          Channel channel = connection.createChannel();\n          RabbitMQSpanConsumer consumer = new RabbitMQSpanConsumer(channel, collector, metrics);\n          channel.basicConsume(builder.queue, true, consumerTag, consumer);\n        } catch (IOException e) {\n          throw new IllegalStateException(\"Failed to start RabbitMQ consumer \" + consumerTag, e);","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-collector/rabbitmq/src/main/java/zipkin2/collector/rabbitmq/RabbitMQCollector.java#L160-L196","documentation":"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().","triggerScenarios":"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().","commonSituations":"Container orchestration starting the collector before RabbitMQ is ready; credentials rotated but the collector config not updated; firewall/NetworkPolicy blocking AMQP port 5672.","solutions":["Verify broker reachability and credentials: try a plain client (rabbitmqadmin or a small amqp client) with the same settings","If the queue may not exist, note declareQueueIfMissing only passively checks first — ensure the queue exists or the broker allows declaration","Fix the address list/vhost/credentials in the ConnectionFactory or addresses() config","For startup ordering, delay or retry collector start until the broker health check passes"],"exampleFix":"// before\nConnectionFactory factory = new ConnectionFactory(); // defaults: localhost:5672, guest/guest\nbuilder.connectionFactory(factory); // fails in Docker where broker is 'rabbitmq' host\n\n// after\nConnectionFactory factory = new ConnectionFactory();\nfactory.setHost(\"rabbitmq\");\nfactory.setUsername(\"zipkin\");\nfactory.setPassword(\"secret\");\nbuilder.connectionFactory(factory);","handlingStrategy":"retry","validationCode":"// Pre-flight broker reachability before wiring\ntry (Socket s = new Socket()) {\n  s.connect(new InetSocketAddress(host, port), 2000);\n} catch (IOException e) {\n  throw new IllegalStateException(\"RabbitMQ not reachable at \" + host + \":\" + port, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  collector.check(); // lazy connect\n} catch (UncheckedIOException e) {\n  log.error(\"RabbitMQ connect failed: {}\", e.getCause().getMessage(), e);\n  // schedule retry with backoff; mark collector unhealthy\n}","preventionTips":["Start collectors after the broker health check passes (init containers / depends_on with condition)","Keep broker address and credentials in one verified config source","Monitor collector check() so a lazy-connect failure is visible, since build() succeeds even when the broker is down"],"tags":["rabbitmq","zipkin","connection","io","amqp"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}