apache/seatunnel · error · IllegalArgumentException

Option 'operation_timeout_ms' must be less than half of…

Error message

Option 'operation_timeout_ms' must be less than half of visibility_timeout_seconds

What it means

validate() requires operation_timeout_ms to be strictly less than half of visibility_timeout_seconds (converted to millis). The operation timeout is how long a receive call waits; if it approaches half the visibility window, messages can be received near (or after) the point where safe processing/visibility renewal is impossible. Thrown as IllegalArgumentException from from().

Solutions

1. Lower operation_timeout_ms below visibility_timeout_seconds/2 (e.g. timeout 30000 for visibility 120)
2. Or increase visibility_timeout_seconds so it is more than twice operation_timeout_ms
3. Re-run the job after adjusting either option

Example fix

// before
operation_timeout_ms = 60000
visibility_timeout_seconds = 60
// after
operation_timeout_ms = 30000
visibility_timeout_seconds = 120

if (operationTimeoutMs >= visibilityTimeoutSeconds * 1000L / 2) {
    throw new IllegalArgumentException("operation_timeout_ms must be < visibility_timeout_seconds/2");
}

When it happens

Trigger: from() called where operationTimeoutMillis >= visibilityTimeoutSeconds * 1000 / 2, e.g. operation_timeout_ms=60000 with visibility_timeout_seconds=60.

Common situations: Users raising the poll wait time without raising visibility_timeout_seconds, or copying timeout values between configs with different visibility settings.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

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

Related errors

• Option 'batch_size' must be between 1 and 32
• Option 'field_delimiter' cannot be empty
• Option 'field_delimiter' cannot be empty
• Option 'max_in_flight_messages' must be greater than or…
• Option 'max_in_flight' must be greater than zero

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

Appendix: source

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

                || 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)