apache/seatunnel · error · IllegalArgumentException

retry.max-attempts must be >= 1.

Error message

retry.max-attempts must be >= 1.

What it means

RetryConfig validates retry settings from the agent config. retry.max-attempts is the number of delivery retries and must be at least 1; a value below 1 (0 or negative) would make retries a no-op or underflow, so the constructor throws IllegalArgumentException immediately.

Source

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

import java.io.Serializable;
import java.util.Objects;

@Getter
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.max-attempts to 1 or higher in the YAML.
2. If retries should be effectively disabled, use the minimum (1) or consult the delivery-guarantee setting instead.
3. Validate the value with EdgeAgentRuntimeOptionRules.retryRule before startup.

Example fix

# before
retry:
  max-attempts: 0
# after
retry:
  max-attempts: 3

Integer attempts = config.get(EdgeAgentRuntimeOptions.RETRY_MAX_ATTEMPTS);
if (attempts != null && attempts < 1) {
    throw new IllegalArgumentException("retry.max-attempts must be >= 1");
}

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_MAX_ATTEMPTS is 0 or negative.

Common situations: User sets 'retry.max-attempts: 0' intending to disable retries; copying config from a zero-based system; typos like '-1'.

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.backoff-ms must be >= 0.
• 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/f46423be600c7cb2. Report an issue: GitHub.