alibaba/spring-ai-alibaba · error · IllegalArgumentException

The backoffMultiplier must be >= 1.0

Error message

The backoffMultiplier must be >= 1.0

What it means

ModelRetryInterceptor.Builder.backoffMultiplier() requires a multiplier of at least 1.0 so exponential backoff never shrinks delay between retries. Values below 1.0 are rejected with IllegalArgumentException at build time.

Source

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

		/**
		 * 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;
		}

		/**
		 * Set the backoff factor (the multiplier for the delay time on each retry).
		 * @param backoffMultiplier The retreat factor must be >= 1.0
		 */
		public Builder backoffMultiplier(double backoffMultiplier) {
			if (backoffMultiplier < 1.0) {
				throw new IllegalArgumentException("The backoffMultiplier must be >= 1.0");
			}
			this.backoffMultiplier = backoffMultiplier;
			return this;
		}

		/**
		 * Configure custom retryable exception handling logic
		 * @param predicate Exception detection function
		 */
		public Builder retryableExceptionPredicate(Predicate<Exception> predicate) {
			this.retryableExceptionPredicate = predicate;
			return this;
		}

		public ModelRetryInterceptor build() {
			return new ModelRetryInterceptor(this);
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a multiplier >= 1.0 (1.0 = fixed delay, 2.0 = doubling)
2. Use 1.0 if you want constant delay between retries
3. Fix the config value supplying the multiplier

Example fix

// before
new ModelRetryInterceptor.Builder().backoffMultiplier(0.5)
// after
new ModelRetryInterceptor.Builder().backoffMultiplier(2.0)

if (multiplier < 1.0) { throw new IllegalArgumentException("backoffMultiplier must be >= 1.0"); }
builder.backoffMultiplier(multiplier);

boolean isValidMultiplier(double m) { return m >= 1.0; }

try { builder.backoffMultiplier(v); } catch (IllegalArgumentException e) { log.warn("Bad backoffMultiplier, defaulting to 2.0", e); builder.backoffMultiplier(2.0); }

When it happens

Trigger: Calling backoffMultiplier() with a double < 1.0, e.g. backoffMultiplier(0.5) or backoffMultiplier(0).

Common situations: Confusing multiplier with a decay percentage; copying config from a library where 0.5 means something else; typos like 1.O vs 1.0.

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

• maxDelay must be greater than or equal to 0.
• maxAttempts must be >= 1
• ${type} requires 'name' field
• maxConcurrency must be at least 1, but got:
• Retry interrupted

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