spring-projects/spring-ai · error · java.lang.IllegalArgumentException

Title is only valid with task_type=RETRIEVAL_DOCUMENT

Error message

Title is only valid with task_type=RETRIEVAL_DOCUMENT

What it means

The GoogleGenAiTextEmbeddingOptions constructor enforces the Gemini API rule that the 'title' metadata field is only meaningful (and only accepted) when the embedding taskType is RETRIEVAL_DOCUMENT. Supplying a title with any other taskType (or the default-less null taskType at construction time, before defaults are applied) fails fast with this IllegalArgumentException.

Source

Thrown at models/spring-ai-google-genai-embedding/src/main/java/org/springframework/ai/google/genai/text/GoogleGenAiTextEmbeddingOptions.java:74

	 */
	private final @Nullable Integer dimensions;

	/**
	 * Optional title, only valid with task_type=RETRIEVAL_DOCUMENT.
	 */
	private final @Nullable String title;

	/**
	 * When set to true, input text will be truncated. When set to false, an error is returned
	 * if the input text is longer than the maximum length supported by the model. Defaults to true.
	 */
	private final @Nullable Boolean autoTruncate;

	protected GoogleGenAiTextEmbeddingOptions(@Nullable String model, @Nullable TaskType taskType,
			@Nullable Integer dimensions, @Nullable String title, @Nullable Boolean autoTruncate) {
		this.model = (model != null ? model : DEFAULT_MODEL_NAME);
		if (StringUtils.hasText(title) && taskType != TaskType.RETRIEVAL_DOCUMENT) {
			throw new IllegalArgumentException("Title is only valid with task_type=RETRIEVAL_DOCUMENT");
		}
		this.taskType = (taskType != null ? taskType : TaskType.RETRIEVAL_DOCUMENT);
		this.dimensions = dimensions;
		this.title = title;
		this.autoTruncate = autoTruncate;
	}

	public static GoogleGenAiTextEmbeddingOptions.Builder builder() {
		return new Builder();
	}


	// @formatter:on

	@Override
	public @Nullable String getModel() {
		return this.model;
	}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Remove .title(...) from options whose taskType is not RETRIEVAL_DOCUMENT.
2. Set .taskType(TaskType.RETRIEVAL_DOCUMENT) explicitly when a title is required.
3. Use two options objects: one with title + RETRIEVAL_DOCUMENT for indexing, one without title (e.g. RETRIEVAL_QUERY) for queries.

Example fix

// before
var opts = GoogleGenAiTextEmbeddingOptions.builder()
    .title("Product manual")
    .taskType(TaskType.RETRIEVAL_QUERY)
    .build();

// after
var opts = GoogleGenAiTextEmbeddingOptions.builder()
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .title("Product manual")
    .build();

if (StringUtils.hasText(title) && taskType != TaskType.RETRIEVAL_DOCUMENT) {
    throw new IllegalArgumentException("title requires taskType RETRIEVAL_DOCUMENT");
}

When it happens

Trigger: Building GoogleGenAiTextEmbeddingOptions with .title("My Doc") while taskType is RETRIEVAL_QUERY, QUESTION_ANSWERING, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, or left unset (null) — the check runs before the default RETRIEVAL_DOCUMENT is applied.

Common situations: Reusing one options object for both indexing (documents) and querying (queries) and only switching taskType for queries while keeping the title; copying options and forgetting to clear the title when changing taskType; believing title is generic metadata.

Related errors

• No embedding input is provided - all texts are null or empty
• model cannot be null or empty
• model cannot be null or empty
• Title is only valid with task_type=RETRIEVAL_DOCUMENT
• SSE connection '<connectionName>' requires a 'url' property.

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