{"record":{"id":"6ac1efc07db327bc","repo":"spring-projects/spring-ai","slug":"expected-a-list-value-for-s-expression-but-got-6ac1ef","errorCode":null,"errorMessage":"Expected a List value for %s expression but got: %s","messagePattern":"Expected a List value for (.+?) expression but got: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-s3-vector-store/src/main/java/org/springframework/ai/vectorstore/s3/S3VectorStoreFilterExpressionEvaluator.java","lineNumber":154,"sourceCode":"\t\t\ttry {\n\t\t\t\t@SuppressWarnings(\"unchecked\")\n\t\t\t\tint result = comparable.compareTo(filterVal);\n\t\t\t\treturn result;\n\t\t\t}\n\t\t\tcatch (ClassCastException ex) {\n\t\t\t\tthrow new IllegalArgumentException(\"Cannot compare values of incompatible types %s and %s\"\n\t\t\t\t\t.formatted(metaVal.getClass().getName(), filterVal.getClass().getName()), ex);\n\t\t\t}\n\t\t}\n\t\tthrow new IllegalArgumentException(\"Cannot compare values of types %s and %s\"\n\t\t\t.formatted(metaVal.getClass().getName(), filterVal.getClass().getName()));\n\t}\n\n\tprivate List<?> asList(Object value, Filter.Expression expression) {\n\t\tif (value instanceof List<?> list) {\n\t\t\treturn list;\n\t\t}\n\t\tthrow new IllegalArgumentException(\n\t\t\t\t\"Expected a List value for %s expression but got: %s\".formatted(expression.type(), value));\n\t}\n\n}\n","sourceCodeStart":136,"sourceCodeEnd":159,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-s3-vector-store/src/main/java/org/springframework/ai/vectorstore/s3/S3VectorStoreFilterExpressionEvaluator.java#L136-L159","documentation":"S3VectorStore's filter expression evaluator requires the operand of IN/NIN expressions to be a JSON array (List). When the right-hand operand of such a filter expression is any other type (a scalar, a string, a map), asList throws this IllegalArgumentException because the S3 vector store filter syntax can only express set membership against a list.","triggerScenarios":"Calling S3VectorStore similaritySearch (or delete by filter) with a Filter.Expression of type IN or NIN whose right operand is not a java.util.List, e.g. new Filter.Expression(IN, key, new Value(\"usa\")) instead of List.of(\"usa\").","commonSituations":"Building filter expressions programmatically or from user input and passing a single value where a collection is expected; forgetting that IN/NIN must always take a collection operand; parsing a JSON filter where the value was deserialized as a String.","solutions":["Wrap the operand in a List: use List.of(value) or a collection when constructing IN/NIN expressions.","Validate the operand type (value instanceof List) before calling similaritySearch/delete with an IN/NIN expression.","If a scalar equality was intended, use Filter.ExpressionType.EQ instead of IN."],"exampleFix":"// before\nvar expr = new Filter.Expression(IN, new Key(\"country\"), new Value(\"USA\"));\n// after\nvar expr = new Filter.Expression(IN, new Key(\"country\"), new Value(List.of(\"USA\", \"UK\")));","handlingStrategy":"type-guard","validationCode":"if (!(operand instanceof List<?> list)) { throw new IllegalArgumentException(\"IN/NIN operand must be a List\"); }","typeGuard":"static boolean isListOperand(Object v) { return v instanceof List<?>; }","tryCatchPattern":"try { vectorStore.similaritySearch(request); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"Expected a List\")) { /* rebuild expression with List operand */ } else throw e; }","preventionTips":["Always wrap IN/NIN operands in List.of(...) or a collection","Never use IN for scalar equality — use EQ","Unit-test filter builders that generate set-membership expressions"],"tags":["vector-store","filter-expression","aws-s3","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}