What causes "${STAIN_TRACE_MAX_TRACES_PER_SECOND_PER_WORKER} must be >= 0" in apache/seatunnel?

Set the option to a non-negative integer (e.g. 100) in the engine config.

apache/seatunnel · error · IllegalArgumentException

must be >= 0

Error message

${STAIN_TRACE_MAX_TRACES_PER_SECOND_PER_WORKER} must be >= 0

What it means

EngineConfig.setStainTraceMaxTracesPerSecondPerWorker rejects negative values for the per-worker stain-trace sampling budget, throwing IllegalArgumentException naming the STAIN_TRACE_MAX_TRACES_PER_SECOND_PER_WORKER option. The value caps trace events reported per worker per second; it must be >= 0.

Solutions

Set the option to a non-negative integer (e.g. 100) in the engine config.
Use 0 to disable per-worker trace reporting.
Clamp computed values with Math.max(0, v) before the setter.
Remove the key to use the default.

Example fix

// before
stain-trace:
  max-traces-per-second-per-worker: -50
// after
stain-trace:
  max-traces-per-second-per-worker: 100

Defensive patterns

Strategy: validation

Validate before calling

int v = Integer.parseInt(props.getProperty("stain-trace.max-traces-per-second-per-worker", "0"));
if (v < 0) throw new IllegalArgumentException("stain-trace per-worker budget must be >= 0, got " + v);

Try / catch

try {
    engineConfig.setStainTraceMaxTracesPerSecondPerWorker(v);
} catch (IllegalArgumentException e) {
    throw new ConfigValidationException("stain-trace budget invalid: " + v, e);
}

Prevention

Clamp computed budgets with Math.max(0, v) before the setter.
Use 0 explicitly to disable, never negative.
Cover stain-trace config parsing in unit tests.
Lint configs for negative numeric fields.

When it happens

Trigger: Engine YAML (parsed via parseEngineConfig) or a programmatic/test caller supplies a negative int to the setter.

Common situations: Negative number written to disable the feature; sample-rate math producing a negative intermediate fed to the setter; copy-pasted signed constant in fixtures.

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/4d99c27b940fcd49. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-common/src/main/java/org/apache/seatunnel/engine/common/config/EngineConfig.java:242

    public void setTimerFlushPoolSize(int timerFlushPoolSize) {
        checkPositive(
                timerFlushPoolSize,
                ServerConfigOptions.WorkerServerConfigOptions.TIMER_FLUSH_POOL_SIZE.key()
                        + " must be > 0");
        this.timerFlushPoolSize = timerFlushPoolSize;
    }

    public void setStainTraceSampleRate(int stainTraceSampleRate) {
        checkPositive(
                stainTraceSampleRate, ServerConfigOptions.STAIN_TRACE_SAMPLE_RATE + " must be > 0");
        this.stainTraceSampleRate = stainTraceSampleRate;
    }

    public void setStainTraceMaxTracesPerSecondPerWorker(
            int stainTraceMaxTracesPerSecondPerWorker) {
        if (stainTraceMaxTracesPerSecondPerWorker < 0) {
            throw new IllegalArgumentException(
                    ServerConfigOptions.STAIN_TRACE_MAX_TRACES_PER_SECOND_PER_WORKER
                            + " must be >= 0");
        }
        this.stainTraceMaxTracesPerSecondPerWorker = stainTraceMaxTracesPerSecondPerWorker;
    }

    public void setStainTraceMaxEntriesPerTrace(int stainTraceMaxEntriesPerTrace) {
        checkPositive(
                stainTraceMaxEntriesPerTrace,
                ServerConfigOptions.STAIN_TRACE_MAX_ENTRIES_PER_TRACE + " must be > 0");
        this.stainTraceMaxEntriesPerTrace = stainTraceMaxEntriesPerTrace;
    }

    public void setStainTracePropagateToAllSplits(boolean stainTracePropagateToAllSplits) {
        this.stainTracePropagateToAllSplits = stainTracePropagateToAllSplits;
    }

    public String getStainTraceFileBasePath() {

View on GitHub (pinned to cf67b549a7)