alibaba/spring-ai-alibaba · error · IllegalStateException

Emulator model is required

Error message

Emulator model is required

What it means

ToolEmulatorInterceptor.Builder.build() requires an emulator ChatModel; without it there is nothing to generate the emulated tool responses. It throws IllegalStateException at build time rather than failing later mid-execution.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/interceptor/toolemulator/ToolEmulatorInterceptor.java:193

			this.emulateAll = emulateAll;
			return this;
		}

		/**
		 * Set a custom prompt template for emulation.
		 * The template should accept 3 string format arguments:
		 * 1. Tool name
		 * 2. Tool description
		 * 3. Tool arguments (JSON)
		 */
		public Builder promptTemplate(String template) {
			this.promptTemplate = template;
			return this;
		}

		public ToolEmulatorInterceptor build() {
			if (emulatorModel == null) {
				throw new IllegalStateException("Emulator model is required");
			}
			return new ToolEmulatorInterceptor(this);
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Call .emulatorModel(chatModel) with a ChatModel instance before build()
2. Inject a model bean (e.g. DashScope/OpenAI ChatModel) in the test/app context
3. Assert the model is configured before building the interceptor

Example fix

// before
ToolEmulatorInterceptor.builder().build();
// after
ToolEmulatorInterceptor.builder().emulatorModel(chatModel).build();

if (chatModel == null) { throw new IllegalStateException("Provide a ChatModel for the tool emulator"); }
ToolEmulatorInterceptor.builder().emulatorModel(chatModel).build();

boolean isModelConfigured(ChatModel m) { return m != null; }

try { interceptor = builder.build(); } catch (IllegalStateException e) { interceptor = builder.emulatorModel(defaultChatModel).build(); }

When it happens

Trigger: Calling ToolEmulatorInterceptor.Builder.build() without ever calling the setter that supplies emulatorModel, or setting it to null conditionally.

Common situations: Copying builder code and omitting the model line; wiring the emulator in tests where a real model bean was not injected; a nullable model property resolved from config that was absent.

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

• SkillRegistry must be provided. Use SkillsAgentHook to load
• RuntimeException wrapping SQLException from PostgresSaver co
• Either chatClient or model must be provided
• Name must be provided
• Description must be provided

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