alibaba/spring-ai-alibaba · error · IllegalArgumentException

initialDelay must be greater than or equal to 0.

Error message

initialDelay must be greater than or equal to 0.

What it means

ModelRetryInterceptor.Builder.initialDelay(long) validates that the initial backoff delay in milliseconds is non-negative. A negative value throws IllegalArgumentException during building, since a negative sleep/delay is meaningless.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/interceptor/modelretry/ModelRetryInterceptor.java:312

		/**
		 * Set the maximum number of retries (including the first call).
		 * @param maxAttempts The maximum number of attempts must be >= 1.
		 */
		public Builder maxAttempts(int maxAttempts) {
			if (maxAttempts < 1) {
				throw new IllegalArgumentException("maxAttempts must be greater than or equal to 1");
			}
			this.maxAttempts = maxAttempts;
			return this;
		}

		/**
		 * Set the initial retry delay (milliseconds).
		 * @param initialDelay Initial delay time, in milliseconds
		 */
		public Builder initialDelay(long initialDelay) {
			if (initialDelay < 0) {
				throw new IllegalArgumentException("initialDelay must be greater than or equal to 0.");
			}
			this.initialDelay = initialDelay;
			return this;
		}

		/**
		 * Set the maximum retry delay (milliseconds).
		 * @param maxDelay Maximum delay time, in milliseconds
		 */
		public Builder maxDelay(long maxDelay) {
			if (maxDelay < 0) {
				throw new IllegalArgumentException("maxDelay must be greater than or equal to 0.");
			}
			this.maxDelay = maxDelay;
			return this;
		}

		/**

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass 0 or a positive millisecond value; use 0 to disable the wait between retries.
2. Clamp configuration: Math.max(0, configuredInitialDelay).
3. Parse durations with proper types (Duration.ofMillis) rather than raw signed arithmetic.

Example fix

// before
retryBuilder.initialDelay(cfg.retryDelayMs()); // -1 when unset
// after
retryBuilder.initialDelay(Math.max(0, cfg.retryDelayMs() > 0 ? cfg.retryDelayMs() : 0));

public static ModelRetryInterceptor buildRetry(long initialDelayMs) {
    if (initialDelayMs < 0) throw new IllegalArgumentException("initialDelay must be >= 0 ms");
    return ModelRetryInterceptor.builder().initialDelay(initialDelayMs).build();
}

try {
    builder.initialDelay(cfg.initialDelayMs());
} catch (IllegalArgumentException e) {
    log.warn("Invalid initialDelay ({} ms), defaulting to 1000 ms", cfg.initialDelayMs());
    builder.initialDelay(1000);
}

When it happens

Trigger: Calling ModelRetryInterceptor.builder().initialDelay(negativeLong) — usually from a mis-signed config value, a subtraction-derived duration, or a typo like initialDelay(-1) intending 'no delay'.

Common situations: Configuring delays via properties/env where a negative value slipped in; computing initialDelay from a Duration with an overflow/sign error; copying a template and editing values incorrectly; intending zero delay but passing -1.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• At least one fallback model must be specified
• maxAttempts must be greater than or equal to 1
• maxContentLength must be positive
• maxCachedThreads must be greater than or equal to 0
• '%s' cannot be blank

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/eddc332b047cc69e. Report an issue: GitHub.