{"record":{"id":"f6ee183299700e62","repo":"spring-projects/spring-ai","slug":"title-is-only-valid-with-task-type-retrieval-docum","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":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"models/spring-ai-google-genai-embedding/src/main/java/org/springframework/ai/google/genai/text/GoogleGenAiTextEmbeddingOptions.java","lineNumber":74,"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 GoogleGenAiTextEmbeddingOptions(@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 GoogleGenAiTextEmbeddingOptions.Builder builder() {\n\t\treturn new Builder();\n\t}\n\n\n\t// @formatter:on\n\n\t@Override\n\tpublic @Nullable String getModel() {\n\t\treturn this.model;\n\t}","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/models/spring-ai-google-genai-embedding/src/main/java/org/springframework/ai/google/genai/text/GoogleGenAiTextEmbeddingOptions.java#L56-L92","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove .title(...) from options whose taskType is not RETRIEVAL_DOCUMENT.","Set .taskType(TaskType.RETRIEVAL_DOCUMENT) explicitly when a title is required.","Use two options objects: one with title + RETRIEVAL_DOCUMENT for indexing, one without title (e.g. RETRIEVAL_QUERY) for queries."],"exampleFix":"// before\nvar opts = GoogleGenAiTextEmbeddingOptions.builder()\n    .title(\"Product manual\")\n    .taskType(TaskType.RETRIEVAL_QUERY)\n    .build();\n\n// after\nvar opts = GoogleGenAiTextEmbeddingOptions.builder()\n    .taskType(TaskType.RETRIEVAL_DOCUMENT)\n    .title(\"Product manual\")\n    .build();","handlingStrategy":"validation","validationCode":"if (StringUtils.hasText(title) && taskType != TaskType.RETRIEVAL_DOCUMENT) {\n    throw new IllegalArgumentException(\"title requires taskType RETRIEVAL_DOCUMENT\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only set title on options used for document indexing, never for query embeddings.","Keep separate options objects for indexing vs querying.","Clear the title whenever changing taskType away from RETRIEVAL_DOCUMENT."],"tags":["embedding","options","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"}