spring-projects/spring-ai · error · IllegalArgumentException

Title is only valid with task_type=RETRIEVAL_DOCUMENT

Error message

Title is only valid with task_type=RETRIEVAL_DOCUMENT

What it means

Vertex AI text embedding models only accept a 'title' parameter when the task type is RETRIEVAL_DOCUMENT (titles help document-side retrieval embeddings). Setting a title with any other taskType is rejected at options construction with an IllegalArgumentException to prevent a pointless/invalid API request.

Source

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

	 */
	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 VertexAiTextEmbeddingOptions(@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 VertexAiTextEmbeddingOptions.Builder builder() {
		return new Builder();
	}


	// @formatter:on

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

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Set taskType to TaskType.RETRIEVAL_DOCUMENT when using a title
2. Remove the title for other task types
3. Use separate options objects: one for documents (title + RETRIEVAL_DOCUMENT), one for queries (RETRIEVAL_QUERY, no title)

Example fix

// before
var opts = VertexAiTextEmbeddingOptions.builder()
    .title("My Doc").taskType(TaskType.RETRIEVAL_QUERY).build(); // throws
// after
var opts = VertexAiTextEmbeddingOptions.builder()
    .title("My Doc").taskType(TaskType.RETRIEVAL_DOCUMENT).build();

boolean valid = !StringUtils.hasText(title) || taskType == TaskType.RETRIEVAL_DOCUMENT; if (!valid) throw new IllegalArgumentException("title requires TaskType.RETRIEVAL_DOCUMENT");

static boolean optionsValid(VertexAiTextEmbeddingOptions o) { return !StringUtils.hasText(o.getTitle()) || o.getTaskType() == TaskType.RETRIEVAL_DOCUMENT; }

try { opts = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Title is only valid")) { opts = builder.taskType(TaskType.RETRIEVAL_DOCUMENT).build(); } else throw e; }

When it happens

Trigger: Building VertexAiTextEmbeddingOptions via builder or constructor with a non-blank title and taskType set to RETRIEVAL_QUERY, QUESTION_ANSWERING, etc. (or left null implicitly resolved only after validation).

Common situations: Reusing a title-bearing options object for query embedding; copying document-embedding config to a query path; setting title from properties without adjusting taskType.

Related errors

• model cannot be null or empty
• 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/a204120fde2a306d. Report an issue: GitHub.