{"record":{"id":"a204120fde2a306d","repo":"spring-projects/spring-ai","slug":"title-is-only-valid-with-task-type-retrieval-docum-a20412","errorCode":null,"errorMessage":"Title is only valid with task_type=RETRIEVAL_DOCUMENT","messagePattern":"Title is only valid with task_type=RETRIEVAL_DOCUMENT","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"models/spring-ai-vertex-ai-embedding/src/main/java/org/springframework/ai/vertexai/embedding/text/VertexAiTextEmbeddingOptions.java","lineNumber":72,"sourceCode":"\t */\n\tprivate final @Nullable Integer dimensions;\n\n\t/**\n\t * Optional title, only valid with task_type=RETRIEVAL_DOCUMENT.\n\t */\n\tprivate final @Nullable String title;\n\n\t/**\n\t * When set to true, input text will be truncated. When set to false, an error is returned\n\t * if the input text is longer than the maximum length supported by the model. Defaults to true.\n\t */\n\tprivate final @Nullable Boolean autoTruncate;\n\n\tprotected VertexAiTextEmbeddingOptions(@Nullable String model, @Nullable TaskType taskType,\n\t\t\t@Nullable Integer dimensions, @Nullable String title, @Nullable Boolean autoTruncate) {\n\t\tthis.model = model != null ? model : DEFAULT_MODEL_NAME;\n\t\tif (StringUtils.hasText(title) && taskType != TaskType.RETRIEVAL_DOCUMENT) {\n\t\t\tthrow new IllegalArgumentException(\"Title is only valid with task_type=RETRIEVAL_DOCUMENT\");\n\t\t}\n\t\tthis.taskType = (taskType != null ? taskType : TaskType.RETRIEVAL_DOCUMENT);\n\t\tthis.dimensions = dimensions;\n\t\tthis.title = title;\n\t\tthis.autoTruncate = autoTruncate;\n\t}\n\n\tpublic static VertexAiTextEmbeddingOptions.Builder builder() {\n\t\treturn new Builder();\n\t}\n\n\n\t// @formatter:on\n\n\t@Override\n\tpublic String getModel() {\n\t\treturn this.model;\n\t}","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/models/spring-ai-vertex-ai-embedding/src/main/java/org/springframework/ai/vertexai/embedding/text/VertexAiTextEmbeddingOptions.java#L54-L90","documentation":"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.","triggerScenarios":"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).","commonSituations":"Reusing a title-bearing options object for query embedding; copying document-embedding config to a query path; setting title from properties without adjusting taskType.","solutions":["Set taskType to TaskType.RETRIEVAL_DOCUMENT when using a title","Remove the title for other task types","Use separate options objects: one for documents (title + RETRIEVAL_DOCUMENT), one for queries (RETRIEVAL_QUERY, no title)"],"exampleFix":"// before\nvar opts = VertexAiTextEmbeddingOptions.builder()\n    .title(\"My Doc\").taskType(TaskType.RETRIEVAL_QUERY).build(); // throws\n// after\nvar opts = VertexAiTextEmbeddingOptions.builder()\n    .title(\"My Doc\").taskType(TaskType.RETRIEVAL_DOCUMENT).build();","handlingStrategy":"validation","validationCode":"boolean valid = !StringUtils.hasText(title) || taskType == TaskType.RETRIEVAL_DOCUMENT; if (!valid) throw new IllegalArgumentException(\"title requires TaskType.RETRIEVAL_DOCUMENT\");","typeGuard":"static boolean optionsValid(VertexAiTextEmbeddingOptions o) { return !StringUtils.hasText(o.getTitle()) || o.getTaskType() == TaskType.RETRIEVAL_DOCUMENT; }","tryCatchPattern":"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; }","preventionTips":["Only set title in document-embedding (retrieval) flows","Keep separate option sets for document vs query embedding","Audit option factories that copy title across contexts"],"tags":["java","google-vertex-ai","validation","task-type"],"backgroundTag":"conflicting-config-options","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}