apache/seatunnel · critical · AzureQueueConnectorException

CONNECTION_FAILED

CONNECTION_FAILED

Error message

Failed to create Azure Queue Storage client for queue ${config.getQueueName()}

What it means

AzureQueueStorageReceiver.create() wraps any failure building the synchronous Azure Queue client in AzureQueueConnectorException(CONNECTION_FAILED), with the queue name in the message. The source cannot receive messages because client construction (auth/endpoint/network) failed.

Source

Thrown at seatunnel-connectors-v2/connector-azure-queue-storage/src/main/java/org/apache/seatunnel/connectors/seatunnel/azure/queue/source/AzureQueueStorageReceiver.java:54

    private final QueueClient queueClient;
    private final Duration visibilityTimeout;
    private final Duration operationTimeout;

    private AzureQueueStorageReceiver(
            QueueClient queueClient, Duration visibilityTimeout, Duration operationTimeout) {
        this.queueClient = queueClient;
        this.visibilityTimeout = visibilityTimeout;
        this.operationTimeout = operationTimeout;
    }

    static AzureQueueReceiver create(AzureQueueSourceConfig config) {
        try {
            return new AzureQueueStorageReceiver(
                    AzureQueueClientFactory.builder(config).buildClient(),
                    Duration.ofSeconds(config.getVisibilityTimeoutSeconds()),
                    Duration.ofMillis(config.getOperationTimeoutMillis()));
        } catch (Exception e) {
            throw new AzureQueueConnectorException(
                    AzureQueueConnectorErrorCode.CONNECTION_FAILED,
                    "Failed to create Azure Queue Storage client for queue "
                            + config.getQueueName(),
                    e);
        }
    }

    @Override
    public List<AzureQueueMessage> receive(int maxMessages) {
        List<AzureQueueMessage> messages = new ArrayList<>(maxMessages);
        for (QueueMessageItem message :
                queueClient.receiveMessages(
                        maxMessages, visibilityTimeout, operationTimeout, Context.NONE)) {
            messages.add(
                    new AzureQueueMessage(
                            message.getMessageId(),
                            message.getPopReceipt(),
                            message.getBody().toString(),

View on GitHub (pinned to cf67b549a7)

Solutions

Verify the connection string or account name/key in the source config
Check network reachability to the queue endpoint from the worker nodes
If keys were rotated, update the config with the new key and restart
Inspect the wrapped cause exception for the specific SDK error

Example fix

// before (rotated key)
account_key = "old-key=="
// after
account_key = "new-key=="

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify endpoint reachability before submitting
InetAddress.getByName("<account>.queue.core.windows.net");

Try / catch

try {
    receiver = AzureQueueStorageReceiver.create(config);
} catch (AzureQueueConnectorException e) {
    if (e.getErrorCode() == AzureQueueConnectorErrorCode.CONNECTION_FAILED) {
        LOG.error("Azure queue source client init failed for queue {}", config.getQueueName(), e.getCause());
    }
    throw e;
}

Prevention

Validate credentials and endpoint (correct cloud suffix) in CI
Check firewall/VNet rules allow worker node egress
Re-test configs after key rotation
Include cause-exception inspection in runbooks

When it happens

Trigger: AzureQueueClientFactory.builder(config).buildClient() throws during source reader initialization — bad credentials, malformed endpoint, or unreachable storage account.

Common situations: Misconfigured account name/key, storage account in another cloud (gov/China) with wrong endpoint suffix, DNS or firewall blocking the cluster, expired storage keys after rotation.

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

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