apache/seatunnel · error · IllegalArgumentException

Option 'visibility_timeout_seconds' must be between 1 and 60

Error message

Option 'visibility_timeout_seconds' must be between 1 and 604800

What it means

AzureQueueSourceConfig.validate throws this when visibility_timeout_seconds is outside the 1..604800 range. 604800s (7 days) is the Azure Storage Queue service maximum; anything below 1s makes messages immediately re-visible.

Source

Thrown at seatunnel-connectors-v2/connector-azure-queue-storage/src/main/java/org/apache/seatunnel/connectors/seatunnel/azure/queue/config/AzureQueueSourceConfig.java:92

                                config.get(AzureQueueStorageSourceOptions.MAX_IN_FLIGHT_MESSAGES))
                        .operationTimeoutMillis(
                                config.get(AzureQueueStorageSourceOptions.OPERATION_TIMEOUT_MS))
                        .build();
        sourceConfig.validate();
        return sourceConfig;
    }

    private void validate() {
        AzureQueueConfigValidator.validateClient(this);
        if (format == MessageFormat.TEXT && fieldDelimiter.isEmpty()) {
            throw new IllegalArgumentException("Option 'field_delimiter' cannot be empty");
        }
        if (batchSize < 1 || batchSize > MAX_BATCH_SIZE) {
            throw new IllegalArgumentException("Option 'batch_size' must be between 1 and 32");
        }
        if (visibilityTimeoutSeconds < 1
                || visibilityTimeoutSeconds > MAX_VISIBILITY_TIMEOUT_SECONDS) {
            throw new IllegalArgumentException(
                    "Option 'visibility_timeout_seconds' must be between 1 and 604800");
        }
        if (pollIntervalMillis <= 0) {
            throw new IllegalArgumentException(
                    "Option 'poll_interval_ms' must be greater than zero");
        }
        if (maxInFlightMessages < batchSize) {
            throw new IllegalArgumentException(
                    "Option 'max_in_flight_messages' must be greater than or equal to batch_size");
        }
        if (operationTimeoutMillis <= 0) {
            throw new IllegalArgumentException(
                    "Option 'operation_timeout_ms' must be greater than zero");
        }
        long visibilityTimeoutMillis = visibilityTimeoutSeconds * 1_000L;
        if (operationTimeoutMillis >= visibilityTimeoutMillis / 2) {
            throw new IllegalArgumentException(
                    "Option 'operation_timeout_ms' must be less than half of visibility_timeout_seconds");

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set visibility_timeout_seconds between 1 and 604800 (7 days)
2. Remove the option to use the plugin default
3. If messages must stay hidden longer than 7 days, redesign processing cadence rather than raising the value

Example fix

// before
visibility_timeout_seconds = 1000000
// after
visibility_timeout_seconds = 3600

java
if (visibilityTimeoutSeconds < 1 || visibilityTimeoutSeconds > 604800) {
    throw new IllegalArgumentException("visibility_timeout_seconds must be 1..604800");
}

java
try {
    AzureQueueSourceConfig.from(config);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("visibility_timeout_seconds")) {
        log.error("Set visibility_timeout_seconds within 1s..7d");
    } else { throw e; }
}

When it happens

Trigger: Building AzureQueueSourceConfig via from() with visibility_timeout_seconds < 1 or > 604800, e.g. visibility_timeout_seconds = 0 or 1000000.

Common situations: User wanted 'no visibility timeout' and set 0; confusion between seconds and milliseconds; exceeding the 7-day Azure service cap when trying to hold messages long-term.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Option 'operation_timeout_ms' must be greater than zero
• Option 'field_delimiter' cannot be empty
• Option 'batch_size' must be between 1 and 32
• Option 'poll_interval_ms' must be greater than zero
• Option 'max_in_flight_messages' must be greater than or equa

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