spring-projects/spring-ai · error · IllegalStateException

argumentConsumer is required

Error message

argumentConsumer is required

What it means

AugmentedToolCallbackProvider.Builder.build() validates that an argumentConsumer was registered before constructing the provider. The argumentConsumer supplies the augmented tool arguments (e.g. extra properties injected into the tool input schema) and without it the provider cannot build its AugmentedToolCallback. This is an IllegalStateException thrown to fail fast on an incomplete builder configuration.

Source

Thrown at spring-ai-model/src/main/java/org/springframework/ai/tool/augment/AugmentedToolCallbackProvider.java:150

		 * @param removeExtraArgumentsAfterProcessing true to remove extra arguments
		 * @return this builder
		 */
		public Builder<T> removeExtraArgumentsAfterProcessing(boolean removeExtraArgumentsAfterProcessing) {
			this.removeExtraArgumentsAfterProcessing = removeExtraArgumentsAfterProcessing;
			return this;
		}

		/**
		 * Builds the {@link AugmentedToolCallbackProvider} instance.
		 * @return the built instance
		 * @throws IllegalStateException if required fields are not set
		 */
		public AugmentedToolCallbackProvider<T> build() {
			if (this.argumentType == null) {
				throw new IllegalStateException("argumentType is required");
			}
			if (this.argumentConsumer == null) {
				throw new IllegalStateException("argumentConsumer is required");
			}

			if (this.delegate != null && this.toolObject != null) {
				throw new IllegalStateException("Cannot set both delegate and toolObject");
			}

			if (this.delegate == null && this.toolObject == null) {
				throw new IllegalStateException("Either delegate or toolObject must be set");
			}

			if (this.toolObject != null) {
				return new AugmentedToolCallbackProvider<>(this.toolObject, this.argumentType, this.argumentConsumer,
						this.removeExtraArgumentsAfterProcessing);
			}
			else if (this.delegate != null) { // Redundant if condition to please NullAway
				return new AugmentedToolCallbackProvider<>(this.delegate, this.argumentType, this.argumentConsumer,
						this.removeExtraArgumentsAfterProcessing);
			}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Add .argumentConsumer(...) to the builder chain before build(), e.g. builder().argumentType(MyArgs.class).argumentConsumer(args -> {...}).
2. If no augmentation is needed, use the original ToolCallbackProvider instead of AugmentedToolCallbackProvider.
3. Wrap builder construction in a shared factory method that always sets both argumentType and argumentConsumer.

Example fix

// before
var provider = AugmentedToolCallbackProvider.builder()
    .argumentType(UserLookupArgs.class)
    .build();
// after
var provider = AugmentedToolCallbackProvider.builder()
    .argumentType(UserLookupArgs.class)
    .argumentConsumer(args -> Map.of("userId", args.userId()))
    .build();

if (builder == null || argumentType == null || argumentConsumer == null) {
    throw new IllegalArgumentException("AugmentedToolCallbackProvider requires argumentType and argumentConsumer");
}

try { provider = builder.build(); } catch (IllegalStateException e) { log.error("Builder misconfigured: {}", e.getMessage()); throw new ConfigurationException(e); }

When it happens

Trigger: Calling AugmentedToolCallbackProvider.builder().argumentType(SomeRecord.class).build() without invoking .argumentConsumer(...) before build().

Common situations: Copying builder code and dropping the argumentConsumer line; assuming argumentType alone is sufficient; building the provider programmatically from config where the consumer lambda was optional.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Either delegate or toolObject must be set
• Either outputType or outputJsonSchema must be set.
• argumentType is required
• Cannot set both delegate and toolObject
• Bean must not be null

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/f01934f1815d56fc. Report an issue: GitHub.