apache/seatunnel · critical · AzureQueueConnectorException

CONNECTION_FAILED

CONNECTION_FAILED

Error message

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

What it means

AzureQueueStorageSender.create() wraps any exception from building the Azure Queue Storage async client in an AzureQueueConnectorException with code CONNECTION_FAILED, including the queue name as context. This means client construction (auth, endpoint parsing, connection) failed before any message could be sent.

Source

Thrown at seatunnel-connectors-v2/connector-azure-queue-storage/src/main/java/org/apache/seatunnel/connectors/seatunnel/azure/queue/sink/AzureQueueStorageSender.java:42

import com.azure.storage.queue.QueueAsyncClient;

import java.util.concurrent.CompletableFuture;

class AzureQueueStorageSender implements AzureQueueSender {

    private final QueueAsyncClient queueClient;

    private AzureQueueStorageSender(QueueAsyncClient queueClient) {
        this.queueClient = queueClient;
    }

    static AzureQueueSender create(AzureQueueSinkConfig config) {
        try {
            return new AzureQueueStorageSender(
                    AzureQueueClientFactory.builder(config).buildAsyncClient());
        } catch (Exception e) {
            throw new AzureQueueConnectorException(
                    AzureQueueConnectorErrorCode.CONNECTION_FAILED,
                    "Failed to create Azure Queue Storage client for queue "
                            + config.getQueueName(),
                    e);
        }
    }

    @Override
    public CompletableFuture<Void> send(String message) {
        return queueClient.sendMessage(message).then().toFuture();
    }

    @Override
    public void close() {
        // QueueAsyncClient has no close contract; its Reactor resources are process-wide.
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Verify connection string / account name / account key or endpoint in the sink config
Test connectivity to the storage account (nslookup/curl the account URL) from the job host
Confirm the queue exists and credentials have send permissions
Check that the exception cause (attached as `e`) for the underlying SDK error

Example fix

// before
url = "https://mystorageaccount.queue.core.windows.net"
// after (verify account name matches the endpoint)
url = "https://correctaccount.queue.core.windows.net"

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check reachability
new URL("https://<account>.queue.core.windows.net").openConnection().connect();

Try / catch

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

Prevention

Validate connection strings/account keys before deploying
Test storage endpoint reachability from worker nodes
Keep credentials in sync after key rotation
Grant least-privilege queue permissions

When it happens

Trigger: AzureQueueClientFactory.builder(config).buildAsyncClient() throws — invalid connection string/account name/key, malformed endpoint, DNS/network failure reaching the storage account, or missing queue permissions.

Common situations: Wrong storage account name or key in config, typo in connection string, storage account deleted/renamed, firewall/VNet blocking access, or no network egress from the cluster.

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/b6096a47a9e2a7be. Report an issue: GitHub.