spring-projects/spring-ai · error · IllegalArgumentException

model cannot be null or empty

Error message

model cannot be null or empty

What it means

The text embedding model validates that resolved options carry a non-empty model name before sending the request. Vertex AI requires an endpoint/model identifier; if options.getModel() is null or blank after merging request options with defaults, the request cannot be built and an IllegalArgumentException is thrown from buildEmbeddingRequest.

Source

Thrown at models/spring-ai-vertex-ai-embedding/src/main/java/org/springframework/ai/vertexai/embedding/text/VertexAiTextEmbeddingModel.java:200

						ModelOptionsUtils.mergeOption(requestOptions.getDimensions(), this.options.getDimensions()));

			if (requestOptions instanceof VertexAiTextEmbeddingOptions vertexOptions) {
				builder.taskType(ModelOptionsUtils.mergeOption(vertexOptions.getTaskType(), this.options.getTaskType()))
					.title(ModelOptionsUtils.mergeOption(vertexOptions.getTitle(), this.options.getTitle()))
					.autoTruncate(ModelOptionsUtils.mergeOption(vertexOptions.getAutoTruncate(),
							this.options.getAutoTruncate()));
			}
			else {
				builder.taskType(this.options.getTaskType())
					.title(this.options.getTitle())
					.autoTruncate(this.options.getAutoTruncate());
			}
			options = builder.build();
		}

		// Validate request options
		if (!StringUtils.hasText(options.getModel())) {
			throw new IllegalArgumentException("model cannot be null or empty");
		}

		return new EmbeddingRequest(embeddingRequest.getInstructions(), options);
	}

	protected PredictRequest.Builder getPredictRequestBuilder(EmbeddingRequest request, EndpointName endpointName,
			VertexAiTextEmbeddingOptions finalOptions) {
		PredictRequest.Builder predictRequestBuilder = PredictRequest.newBuilder().setEndpoint(endpointName.toString());

		TextParametersBuilder parametersBuilder = TextParametersBuilder.of();

		if (finalOptions.getAutoTruncate() != null) {
			parametersBuilder.autoTruncate(finalOptions.getAutoTruncate());
		}

		if (finalOptions.getDimensions() != null) {
			parametersBuilder.outputDimensionality(finalOptions.getDimensions());
		}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Set the model explicitly: .model("textembedding-gecko@003") or the desired version
2. Ensure your config property (spring.ai.vertex.ai.embedding.text.options.model) is not blank
3. Use VertexAiTextEmbeddingOptions.builder() defaults and only override fields you need
4. Validate the model string before constructing the EmbeddingRequest

Example fix

// before
var options = VertexAiTextEmbeddingOptions.builder().build();
options.setModel(""); // blank -> throws
// after
var options = VertexAiTextEmbeddingOptions.builder()
    .model("textembedding-gecko@003")
    .build();

Assert.hasText(options.getModel(), "Vertex AI embedding model must be set, e.g. textembedding-gecko@003");

static boolean validModel(VertexAiTextEmbeddingOptions o) { return o != null && StringUtils.hasText(o.getModel()); }

try { return model.call(request); } catch (IllegalArgumentException e) { if (e.getMessage().contains("model cannot be null")) { /* rebuild options with default model */ } throw e; }

When it happens

Trigger: Calling VertexAiTextEmbeddingModel.call()/embed() with EmbeddingRequest options (or a defaultOptions instance) where the 'model' field is set to null or "" in a way that overrides the default model name; constructing options programmatically with new VertexAiTextEmbeddingOptions.builder().model(null)...

Common situations: Upgrading Spring AI versions where default options changed; copying builder code and omitting .model(); building options dynamically from config where the model property is an empty string.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Title is only valid with task_type=RETRIEVAL_DOCUMENT
• Method must have exactly 1 parameter (List<McpSchema.Resourc
• Method must have void or Mono<Void> return type:
• Method must have void return type: " + method.getName() + "
• clients must not be empty

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