What causes "${optionPath} must be >= ${min} when set." in apache/seatunnel?

Set the offending option at to a value >= the stated minimum.

apache/seatunnel · error · IllegalArgumentException

must be >= when set.

Error message

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

What it means

AgentSchedulerConfig.requireAtLeast(int,...) validates integer scheduler options against a minimum. When an option is set but below the allowed minimum, the config constructor throws IllegalArgumentException of the form '<optionPath> must be >= <min> when set.' This guards against nonsensical settings like zero or negative pool sizes or intervals.

Solutions

Set the offending option at <optionPath> to a value >= the stated minimum.
Remove the option so it falls back to the built-in default.
Read the error's optionPath and min to identify exactly which option and threshold applies.
Review AgentSchedulerConfig's constructor to see all requireAtLeast calls and pick compliant values.

Example fix

// before (config)
scheduler { poll-interval-ms = 0 }
// after (config, assuming min 100)
scheduler { poll-interval-ms = 500 }

Defensive patterns

Strategy: validation

Validate before calling

# preflight in Python before submitting agent config
MIN = {'poll-interval-ms': 100, 'batch-size': 1}
for key, m in MIN.items():
    v = scheduler_cfg.get(key)
    if v is not None and v < m:
        raise ValueError(f'scheduler.{key} must be >= {m} when set.')

Try / catch

try {
    AgentSchedulerConfig.from(config);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("must be >= ")) {
        log.error("Scheduler option out of range: {}", e.getMessage());
    }
}

Prevention

Validate the whole scheduler config block against documented minimums before submission.
Avoid overriding options with 0; remove the key to use the compliant built-in default.
Check the error's optionPath first; it names the exact config key to fix.

When it happens

Trigger: Building AgentSchedulerConfig.from(config) where a numeric option (interval, batch size, or thread count at its optionPath) is present but less than the documented minimum.

Common situations: Users set a scheduler interval or batch size to 0 in the HOCON/JSON config; scripts generate configs with uninitialized 0 values; tests build configs that fail minimum bounds.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

        ConfigValidator.of(config).validate(EdgeAgentRuntimeOptionRules.runtimeRule());

        this.idleSleepMs = config.get(EdgeAgentRuntimeOptions.RUNTIME_IDLE_SLEEP_MS);
        requireAtLeast(this.idleSleepMs, 1L, "agent.idle-sleep-ms");

        this.bulkMaxSize = config.get(EdgeAgentRuntimeOptions.RUNTIME_BULK_MAX_SIZE);
        requireAtLeast(this.bulkMaxSize, 1, "agent.bulk-max-size");

        this.flushIntervalMs = config.get(EdgeAgentRuntimeOptions.RUNTIME_FLUSH_INTERVAL_MS);
        requireAtLeast(this.flushIntervalMs, 1L, "agent.flush-interval-ms");
    }

    public static AgentSchedulerConfig from(ReadonlyConfig config) {
        return new AgentSchedulerConfig(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)