spring-projects/spring-ai · error · IllegalArgumentException

model cannot be null or empty

Error message

model cannot be null or empty

What it means

OllamaEmbeddingModel.buildEmbeddingRequest() merges the request options with defaults and validates that a model name is present, since Ollama embeddings require an explicit model. If the merged options' model is null/empty, IllegalArgumentException('model cannot be null or empty') is thrown.

Source

Thrown at models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/OllamaEmbeddingModel.java:153

				EmbeddingResponse embeddingResponse = new EmbeddingResponse(embeddings, embeddingResponseMetadata);

				observationContext.setResponse(embeddingResponse);

				return embeddingResponse;
			});
	}

	private DefaultUsage getDefaultUsage(OllamaApi.EmbeddingsResponse response) {
		return new DefaultUsage(Optional.ofNullable(response.promptEvalCount()).orElse(0), 0);
	}

	EmbeddingRequest buildEmbeddingRequest(EmbeddingRequest embeddingRequest) {
		OllamaEmbeddingOptions requestOptions = mergeOptions(embeddingRequest.getOptions());

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

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

	private OllamaEmbeddingOptions mergeOptions(@Nullable EmbeddingOptions requestOptions) {
		OllamaEmbeddingOptions options = this.options;

		if (requestOptions == null) {
			return options;
		}

		OllamaEmbeddingOptions.Builder builder = OllamaEmbeddingOptions.builder()
			.model(ModelOptionsUtils.mergeOption(requestOptions.getModel(), options.getModel()))
			.dimensions(ModelOptionsUtils.mergeOption(requestOptions.getDimensions(), options.getDimensions()));

		if (requestOptions instanceof OllamaEmbeddingOptions ro) {
			builder.keepAlive(ModelOptionsUtils.mergeOption(ro.getKeepAlive(), options.getKeepAlive()))

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Set a default embedding model on the builder: OllamaOptions.builder().model("nomic-embed-text").build().
2. Or pass EmbeddingOptions with a model in the EmbeddingRequest.
3. Verify option merge logic isn't clearing the model property.

Example fix

// before
new OllamaEmbeddingModel(api); // no model configured
// after
new OllamaEmbeddingModel(api,
    OllamaOptions.builder().model("nomic-embed-text").build());

var model = embeddingRequest.getOptions() != null ? embeddingRequest.getOptions().getModel() : null;
if (model == null || model.isBlank()) {
    throw new IllegalArgumentException("Embedding model must be set in options or defaults");
}

boolean hasEmbeddingModel(EmbeddingOptions o) { return o != null && o.getModel() != null && !o.getModel().isBlank(); }

try {
    return embeddingModel.embed(texts);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("model cannot be null")) { /* supply model options and retry */ }
    throw e;
}

When it happens

Trigger: Calling embed()/embedForResponse() with an EmbeddingRequest whose options lack a model while the OllamaEmbeddingModel was built without default embedding options specifying a model.

Common situations: Constructing OllamaEmbeddingModel without .defaultOptions(OllamaOptions.builder().model("nomic-embed-text").build()); building EmbeddingRequest with empty EmbeddingOptions at the call site.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• model cannot be null or empty
• SSE connection '<connectionName>' requires a 'url' property.
• No embedding input is provided - instructions list is empty
• model cannot be null or empty
• Unsupported message type:

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