apache/seatunnel · error · AzureQueueConnectorException

READ_FAILED

READ_FAILED

Error message

Failed to receive Azure Queue Storage messages

What it means

The source reader wraps any exception from receiver.receive(batchSize) into an AzureQueueConnectorException (READ_FAILED) with this message. receiver.receive dequeues up to batchSize messages from the Azure Queue; any client-side or service-side failure during that call aborts the poll loop.

Source

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

    public void pollNext(Collector<SeaTunnelRow> output) {
        if (!splitAssigned) {
            return;
        }
        checkVisibilityRenewalFailure();
        int availableCapacity;
        synchronized (acknowledgementLock) {
            availableCapacity = config.getMaxInFlightMessages() - leasedMessages.size();
        }
        if (availableCapacity <= 0) {
            sleepBeforeNextPoll();
            return;
        }

        List<AzureQueueMessage> messages;
        try {
            messages = receiver.receive(Math.min(config.getBatchSize(), availableCapacity));
        } catch (Exception e) {
            throw readFailure("Failed to receive Azure Queue Storage messages", e);
        }
        if (messages.isEmpty()) {
            sleepBeforeNextPoll();
            return;
        }

        synchronized (acknowledgementLock) {
            leasedMessages.addAll(messages);
        }
        for (int index = 0; index < messages.size(); index++) {
            AzureQueueMessage message = messages.get(index);
            try {
                synchronized (output.getCheckpointLock()) {
                    deserializationSchema.deserialize(message.getBody(), output);
                    synchronized (acknowledgementLock) {
                        unacknowledgedMessages.add(message);
                    }
                }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Check the wrapped cause: validate connection string, account name, and queue name in the source config.
  2. Verify the queue exists and the credentials have read/delete (process) permissions.
  3. Test network/firewall access from the cluster to the storage endpoint (storage account firewall/VNet rules).
  4. Add retry/backoff for transient throttling and restart the job from the last checkpoint.

Example fix

// before: typo in queue name
"queue" = "myquue"
// after
"queue" = "myqueue"
Defensive patterns

Strategy: retry

Validate before calling

// validate config before starting the source
QueueClient c = new QueueClientBuilder()
        .connectionString(connStr).queueName(queueName).buildAsyncClient();
c.getProperties().block(Duration.ofSeconds(10)); // fails fast on bad queue/credentials

Try / catch

try {
    reader.pollNext();
} catch (AzureQueueConnectorException e) {
    if (e.getCause() instanceof IOException
            || (e.getCause() instanceof HttpResponseException h && h.getStatusCode() >= 500)) {
        backoffAndRetry();
    } else {
        throw e; // auth/config errors are not retryable
    }
}

Prevention

When it happens

Trigger: pollNext() calls receiver.receive(...) and the Azure Queue Storage SDK throws — invalid/expired credentials, nonexistent queue, network failure, throttling, or SDK client misconfiguration.

Common situations: Wrong connection string or account key; queue name typo or queue deleted; storage account firewall blocking the cluster; receiving before visibility timeout handling with an invalid pop receipt.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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