apache/seatunnel · error · IllegalArgumentException

retry.backoff-max-ms must be >= effective retry.backoff-ms (

Error message

retry.backoff-max-ms must be >= effective retry.backoff-ms (${backoffMs} ms).

What it means

RetryConfig enforces that retry.backoff-max-ms (the cap for exponential backoff) is at least the effective retry.backoff-ms (the base delay). Otherwise backoff would start above its own ceiling, so the constructor throws IllegalArgumentException including the effective base delay.

Source

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

    private final int maxAttempts;
    private final long backoffMs;
    private final long backoffMaxMs;

    public RetryConfig(ReadonlyConfig config) {
        Objects.requireNonNull(config, "config");
        ConfigValidator.of(config).validate(EdgeAgentRuntimeOptionRules.retryRule());

        this.maxAttempts = config.get(EdgeAgentRuntimeOptions.RETRY_MAX_ATTEMPTS);
        if (this.maxAttempts < 1) {
            throw new IllegalArgumentException("retry.max-attempts must be >= 1.");
        }
        this.backoffMs = config.get(EdgeAgentRuntimeOptions.RETRY_BACKOFF_MS);
        if (this.backoffMs < 0L) {
            throw new IllegalArgumentException("retry.backoff-ms must be >= 0.");
        }
        this.backoffMaxMs = config.get(EdgeAgentRuntimeOptions.RETRY_BACKOFF_MAX_MS);
        if (this.backoffMaxMs < this.backoffMs) {
            throw new IllegalArgumentException(
                    "retry.backoff-max-ms must be >= effective retry.backoff-ms ("
                            + this.backoffMs
                            + " ms).");
        }
    }

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

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set retry.backoff-max-ms >= retry.backoff-ms.
2. Recheck both values after any change, since defaults affect the effective base.
3. Remove backoff-max-ms to let it default above the base if unsure.

Example fix

# before
retry:
  backoff-ms: 5000
  backoff-max-ms: 1000
# after
retry:
  backoff-ms: 5000
  backoff-max-ms: 60000

long backoffMs = config.get(EdgeAgentRuntimeOptions.RETRY_BACKOFF_MS);
long backoffMaxMs = config.get(EdgeAgentRuntimeOptions.RETRY_BACKOFF_MAX_MS);
if (backoffMaxMs < backoffMs) {
    throw new IllegalArgumentException("backoff-max-ms must be >= backoff-ms");
}

try { RetryConfig retry = new RetryConfig(config); } catch (IllegalArgumentException e) { log.error("Retry config invalid: {}", e.getMessage()); }

When it happens

Trigger: Constructing RetryConfig where RETRY_BACKOFF_MAX_MS < RETRY_BACKOFF_MS (after defaults are applied).

Common situations: User raises backoff-ms but forgets to raise backoff-max-ms; explicitly setting a small max while a large default base applies; partial copy-paste of retry config.

Related errors

• retry.max-attempts must be >= 1.
• retry.backoff-ms must be >= 0.
• Schema config can not be empty
• Retry times must be greater than 0
• Unknown format type:

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