apache/seatunnel · error · IllegalArgumentException

retry.backoff-ms must be >= 0.

Error message

retry.backoff-ms must be >= 0.

What it means

RetryConfig requires retry.backoff-ms to be non-negative since it is the base delay between retries; a negative delay is meaningless. The constructor throws IllegalArgumentException when the configured value is below 0.

Source

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

public class RetryConfig implements Serializable {

    private static final long serialVersionUID = 1L;

    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-ms to 0 or a positive value.
2. Use 0 if you want no initial backoff delay.
3. Check for accidental negative signs in the retry section.

Example fix

# before
retry:
  backoff-ms: -1000
# after
retry:
  backoff-ms: 1000

Long backoffMs = config.get(EdgeAgentRuntimeOptions.RETRY_BACKOFF_MS);
if (backoffMs != null && backoffMs < 0L) {
    throw new IllegalArgumentException("retry.backoff-ms must be >= 0");
}

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

When it happens

Trigger: Constructing RetryConfig with ReadonlyConfig where EdgeAgentRuntimeOptions.RETRY_BACKOFF_MS is a negative long.

Common situations: Sign typo in YAML ('-1000'); unit confusion leading to negative computed values; hand-edited config files.

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

• retry.max-attempts must be >= 1.
• retry.backoff-max-ms must be >= effective retry.backoff-ms (
• 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/1f85c7b7c307317c. Report an issue: GitHub.