apache/seatunnel · error · IllegalArgumentException

${optionPath} must be >= ${min} when set.

Error message

${optionPath} must be >= ${min} when set.

What it means

QueueConfig.requireAtLeast (int overload) validates that an integer queue option, when explicitly set, meets a minimum threshold. It throws IllegalArgumentException naming the option path and the minimum when the value is below the floor.

Source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/config/QueueConfig.java:73

        requireAtLeast(this.resurrectBatchSize, 1, "queue.resurrect-batch-size");

        this.resurrectIntervalMs = config.get(EdgeAgentRuntimeOptions.QUEUE_RESURRECT_INTERVAL_MS);
        requireAtLeast(this.resurrectIntervalMs, 1L, "queue.resurrect-interval-ms");

        this.cleanupBatchSize = config.get(EdgeAgentRuntimeOptions.QUEUE_CLEANUP_BATCH_SIZE);
        requireAtLeast(this.cleanupBatchSize, 1, "queue.cleanup-batch-size");

        this.ackedRetentionMs = config.get(EdgeAgentRuntimeOptions.QUEUE_ACKED_RETENTION_MS);
        requireAtLeast(this.ackedRetentionMs, 0L, "queue.acked-retention-ms");
    }

    public static QueueConfig from(ReadonlyConfig config) {
        return new QueueConfig(config);
    }

    private static void requireAtLeast(int value, int min, String optionPath) {
        if (value < min) {
            throw new IllegalArgumentException(optionPath + " must be >= " + min + " when set.");
        }
    }

    private static void requireAtLeast(long value, long min, String optionPath) {
        if (value < min) {
            throw new IllegalArgumentException(optionPath + " must be >= " + min + " when set.");
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Raise the offending queue option to at least the stated minimum in the YAML.
2. Read the message's optionPath to identify exactly which option is below minimum.
3. Remove the option to fall back to defaults if a custom small value is not required.

Example fix

# before
queue:
  capacity: 0
# after
queue:
  capacity: 1024

Integer capacity = config.get(QUEUE_CAPACITY_OPTION);
if (capacity != null && capacity < MIN_CAPACITY) {
    throw new IllegalArgumentException("queue capacity must be >= " + MIN_CAPACITY);
}

try { QueueConfig.from(config); } catch (IllegalArgumentException e) { log.error("Queue config invalid: {}", e.getMessage()); }

When it happens

Trigger: Constructing QueueConfig from a ReadonlyConfig where an int queue option (via the int requireAtLeast overload) is set to a value smaller than its declared minimum.

Common situations: User sets a queue capacity/size option to 0 or a negative number in the 'queue' YAML section; unit confusion (bytes vs entries) leading to too-small values.

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.

Related errors

• max_queue_size must be greater than 0, got: ${maxQueueSize}
• Schema config can not be empty
• Unknown format type:
• Option '${option}' cannot be blank
• Option '${valuesAndOptions[index + 1]}' is not valid for the

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