apache/seatunnel · error · AzureQueueConnectorException

VISIBILITY_RENEWAL_FAILED

VISIBILITY_RENEWAL_FAILED

Error message

Azure Queue Storage message visibility renewal failed

What it means

The reader renews message visibility in the background so long-processing messages are not reclaimed by the queue. checkVisibilityRenewalFailure() (called from pollNext) rethrows any stored renewal failure as AzureQueueConnectorException(VISIBILITY_RENEWAL_FAILED), failing the reader rather than silently letting messages become visible again and be reprocessed.

Source

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

            for (List<AzureQueueMessage> pending : pendingAcknowledgements.values()) {
                pending.remove(message);
            }
        }
    }

    private void sleepBeforeNextPoll() {
        try {
            Thread.sleep(config.getPollIntervalMillis());
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw readFailure("Interrupted while polling Azure Queue Storage", e);
        }
    }

    private void checkVisibilityRenewalFailure() {
        Throwable failure = visibilityRenewalFailure.get();
        if (failure != null) {
            throw new AzureQueueConnectorException(
                    AzureQueueConnectorErrorCode.VISIBILITY_RENEWAL_FAILED,
                    "Azure Queue Storage message visibility renewal failed",
                    failure);
        }
    }

    private AzureQueueConnectorException readFailure(String message, Throwable cause) {
        return new AzureQueueConnectorException(
                AzureQueueConnectorErrorCode.READ_FAILED, message, cause);
    }

    @FunctionalInterface
    interface ReceiverFactory {
        AzureQueueReceiver create();
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Retry the job — renewal failures are often transient network/Azure issues
2. Increase visibility_timeout_seconds and/or reduce per-record processing time
3. Verify credentials are valid and not recently rotated
4. Check Azure Storage throttling/metrics (429s) and account availability

Example fix

// before
visibility_timeout_seconds = 30   # renewal under heavy load fails
// after
visibility_timeout_seconds = 300

// Ensure processing time is comfortably within visibility window
if (maxProcessingMs > visibilityTimeoutSeconds * 1000L / 2) {
    LOG.warn("processing time close to visibility timeout; renewal pressure high");
}

try {
    reader.pollNext(collector);
} catch (AzureQueueConnectorException e) {
    if (e.getErrorCode() == AzureQueueConnectorErrorCode.VISIBILITY_RENEWAL_FAILED) {
        LOG.warn("visibility renewal failed; restarting reader", e.getCause());
        // rely on engine restart / checkpoint recovery
    }
    throw e;
}

When it happens

Trigger: A background renewal task stored a Throwable (network error, auth failure, message no longer exists / pop receipt invalid) and pollNext() subsequently checks and surfaces it.

Common situations: Records taking longer than visibility_timeout_seconds combined with renewal HTTP failures, transient Azure outages, expired/rotated credentials, or throttling (429) from the storage account.

Related errors

• CONNECTION_FAILED
• CONNECTION_FAILED
• WRITE_FAILED
• READ_FAILED
• Failed to fetch metadata from Gravitino for metadata: %s

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