apache/seatunnel · error · AzureQueueConnectorException

WRITE_FAILED

WRITE_FAILED

Error message

Failed to send message to Azure Queue Storage

What it means

AzureQueueStorageSinkWriter.write failed to send a row's payload to Azure Queue Storage. The immediate send call threw a RuntimeException, or the async send completed exceptionally — either path releases the permit and throws a SeaTunnelRuntimeException with code WRITE_FAILED.

Source

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

    public void write(SeaTunnelRow row) throws IOException {
        checkSendError();
        byte[] payload = serializationSchema.serialize(row);
        validateMessageSize(payload.length);
        acquireSendPermit();

        try {
            checkSendError();
        } catch (AzureQueueConnectorException e) {
            sendPermits.release();
            throw e;
        }

        CompletableFuture<Void> sendFuture;
        try {
            sendFuture = sender.send(new String(payload, StandardCharsets.UTF_8));
        } catch (RuntimeException e) {
            sendPermits.release();
            throw writeFailure(e);
        }

        pendingSends.add(sendFuture);
        sendFuture.whenComplete(
                (ignored, error) -> {
                    if (error != null) {
                        sendError.compareAndSet(null, unwrap(error));
                    }
                    pendingSends.remove(sendFuture);
                    sendPermits.release();
                });
        checkSendError();
    }

    @Override
    public Optional<Void> prepareCommit() {
        flush();
        return Optional.empty();

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the queue name and storage account in the sink config (endpoint, queue) exist and are spelled correctly
2. Validate credentials/connection string validity and permissions (send rights on the queue)
3. Check network connectivity/DNS from the worker node to the Azure storage endpoint
4. Check the full exception cause chained in WRITE_FAILED for the actual Azure error code (e.g., 403, 404, quota)

// pre-flight: ensure queue exists and credentials work before running the job
QueueClient c = new QueueClientBuilder().connectionString(cs).queueName(queue).buildClient();
if (!c.getQueueName().equals(queue)) throw new IllegalStateException("queue misconfigured");

try { writer.write(row); } catch (SeaTunnelRuntimeException e) { if ("WRITE_FAILED".equals(e.getSeaTunnelErrorCode().getCode())) { /* check Azure error code in cause */ } throw e; }

When it happens

Trigger: sender.send(...) throws synchronously (client closed, invalid queue reference), or the returned CompletableFuture completes exceptionally (queue doesn't exist, auth failure, quota/network errors). Also triggered when a previously failed async send surfaces during a later write.

Common situations: Queue deleted or wrong queue name in config; storage account key/connection string expired or rotated; network partition to Azure storage; exceeding queue message limits.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• READ_FAILED
• Option 'field_delimiter' cannot be empty
• Option 'max_in_flight' must be greater than zero
• Option 'operation_timeout_ms' must be greater than zero
• CONNECTION_FAILED

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