apache/seatunnel · error · RabbitmqConnectorException

RABBITMQ-02

RABBITMQ-02

Error message

Error while creating RMQ client with queue %s at %s

What it means

The RabbitmqClient constructor performs the full client setup: opening a connection, creating the channel, declaring the queue, and applying prefetch (basicQos). Any Exception during this sequence is wrapped in RabbitmqConnectorException with CREATE_RABBITMQ_CLIENT_FAILED and a formatted message naming the queue and host, so the user can tell which broker target failed. The root cause (ConnectException, IOException, timeout, auth failure) is in the cause chain.

Source

Thrown at seatunnel-connectors-v2/connector-rabbitmq/src/main/java/org/apache/seatunnel/connectors/seatunnel/rabbitmq/client/RabbitmqClient.java:72

    /**
     * Constructor for RabbitmqClient.
     *
     * @param config RabbitMQ configuration
     */
    public RabbitmqClient(RabbitmqConfig config) {
        this.config = config;
        try {
            this.connectionFactory = createConnectionFactory();
            this.connection = connectionFactory.newConnection();
            this.channel = connection.createChannel();

            // set channel prefetch count
            if (config.getPrefetchCount() != null) {
                channel.basicQos(config.getPrefetchCount(), true);
            }

        } catch (Exception e) {
            throw new RabbitmqConnectorException(
                    CREATE_RABBITMQ_CLIENT_FAILED,
                    String.format(
                            "Error while creating RMQ client with queue %s at %s",
                            config.getQueueName(), config.getHost()),
                    e);
        }
    }

    /**
     * Get the current RabbitMQ channel.
     *
     * @return RabbitMQ channel
     */
    public Channel getChannel() {
        return channel;
    }

    /**

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the wrapped cause for the concrete failure (connection refused, auth failure, queue declaration mismatch)
2. Verify host, port, virtualHost, username, password and queueName in the source/sink config
3. Ensure the queue exists with the exact same properties (durable, exclusive, auto-delete, arguments) the connector declares, or delete/recreate it consistently
4. Test broker reachability from the worker node: ping/telnet host 5672 (or 5671 for TLS)
5. Check RabbitMQ server logs at the time of the attempt for the channel/connection error

Example fix

// before
# config with mismatched queue args
queue_name=my_queue
# queue exists as non-durable but connector declares durable -> declaration fails
// after
# delete the conflicting queue or align its properties with the connector config
rabbitmqctl delete_queue my_queue
# then rerun; or declare durable=true when creating the queue externally

// pre-flight connectivity and queue check
try (com.rabbitmq.client.Connection c = factory.newConnection()) {
    try (Channel ch = c.createChannel()) {
        ch.queueDeclarePassive(config.getQueueName()); // throws if queue missing/mismatched
    }
}

try {
    new RabbitmqClient(config, ...);
} catch (RabbitmqConnectorException e) {
    if (e.getErrorCode() == RabbitmqConnectorErrorCode.CREATE_RABBITMQ_CLIENT_FAILED) {
        LOG.error("RMQ client creation failed for queue={} host={}: {}",
            config.getQueueName(), config.getHost(), e.getCause());
    } else throw e;
}

When it happens

Trigger: new RabbitmqClient(...) where connection to host fails, queue declaration fails (e.g. PRECONDITION_FAILED due to mismatched queue arguments), basicQos fails, or authentication is rejected.

Common situations: Wrong host/port or broker down; wrong virtual host; queue already exists with different durable/arguments causing declaration failure; wrong username/password; firewall or DNS issues from worker nodes; TLS configuration problems.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• RABBITMQ-07
• RABBITMQ-01
• RABBITMQ-08
• RABBITMQ-09
• RABBITMQ-03

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/c2ed5f795617542f. Report an issue: GitHub.