apache/seatunnel · error · AzureQueueConnectorException

ACKNOWLEDGE_FAILED

ACKNOWLEDGE_FAILED

Error message

Failed to delete Azure Queue Storage messages for checkpoint ${checkpointId}

What it means

When a checkpoint completes, the reader deletes the messages accumulated under that checkpoint. If receiver.delete(message) throws for any message, the reader throws AzureQueueConnectorException(ACKNOWLEDGE_FAILED) naming the checkpointId, so the failure is surfaced to the engine instead of being silently swallowed (messages would reappear after visibility expiry).

Source

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

        List<AzureQueueMessage> messages;
        synchronized (acknowledgementLock) {
            Map.Entry<Long, List<AzureQueueMessage>> checkpoint =
                    pendingAcknowledgements.floorEntry(checkpointId);
            if (checkpoint == null) {
                return;
            }
            messages = new ArrayList<>(checkpoint.getValue());
        }

        for (AzureQueueMessage message : messages) {
            try {
                synchronized (message) {
                    if (!message.isDeleted()) {
                        receiver.delete(message);
                    }
                }
            } catch (Exception e) {
                throw new AzureQueueConnectorException(
                        AzureQueueConnectorErrorCode.ACKNOWLEDGE_FAILED,
                        "Failed to delete Azure Queue Storage messages for checkpoint "
                                + checkpointId,
                        e);
            }
        }

        synchronized (acknowledgementLock) {
            leasedMessages.removeAll(messages);
            unacknowledgedMessages.removeAll(messages);
            pendingAcknowledgements.headMap(checkpointId, true).clear();
            for (List<AzureQueueMessage> pending : pendingAcknowledgements.values()) {
                pending.removeAll(messages);
            }
        }
    }

    @Override

View on GitHub (pinned to cf67b549a7)

Solutions

1. Increase visibility_timeout_seconds so messages stay invisible through checkpoint intervals
2. Retry the job — deletes are retried for messages not yet deleted
3. Ensure checkpoint intervals are shorter than the visibility timeout
4. Inspect the wrapped cause for Azure-specific delete errors

Example fix

// before
visibility_timeout_seconds = 60   # checkpoint interval 120s -> pop receipt expires
// after
visibility_timeout_seconds = 600

// Ensure checkpoint interval fits within visibility window
if (checkpointIntervalMs >= visibilityTimeoutSeconds * 1000L) {
    throw new IllegalArgumentException("checkpoint interval too long for visibility timeout");
}

try {
    reader.notifyCheckpointComplete(checkpointId);
} catch (AzureQueueConnectorException e) {
    if (e.getErrorCode() == AzureQueueConnectorErrorCode.ACKNOWLEDGE_FAILED) {
        // engine will retry/restore; log cause for Azure delete errors
        LOG.warn("Ack failed for checkpoint {}", checkpointId, e.getCause());
    }
}

When it happens

Trigger: notifyCheckpointComplete(checkpointId) iterates pending messages and receiver.delete() raises — e.g. pop receipt expired (visibility elapsed), message already deleted, or transient Azure HTTP errors.

Common situations: Slow checkpoints where processing takes longer than visibility_timeout_seconds so the pop receipt is stale, duplicate deletes from overlapping checkpoints, or Azure throttling/outage during delete.

Related errors

• No checkpoint found for job ${jobId}
• No checkpoint found for job, job id is: ${jobId}
• Option '${option}' cannot be blank
• Option '${valuesAndOptions[index + 1]}' is not valid for the
• Option 'field_delimiter' cannot be empty

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