spring-projects/spring-ai · error · RuntimeException

Unknown compare operator:

Error message

Unknown compare operator:

What it means

The FilterExpressionTextParser converts filter expression DSL text (e.g. "color == 'red'") into Filter.Expression trees. convertCompare looks up the comparison operator token in COMP_EXPRESSION_TYPE_MAP; if the token is not a recognized comparison operator (==, !=, >, >=, <, <=, IN, NIN, etc.) it throws this RuntimeException. This means the filter text contained a token the grammar accepted but that is not a valid comparison operator.

Source

Thrown at spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/filter/FilterExpressionTextParser.java:284

		@Override
		public Filter.Operand visitCompareExpression(FiltersParser.CompareExpressionContext ctx) {
			return new Filter.Expression(this.convertCompare(ctx.compare().getText()), this.visit(ctx.identifier()),
					this.visit(ctx.constant()));
		}

		@Override
		public Filter.Operand visitIsNullExpression(FiltersParser.IsNullExpressionContext ctx) {
			return new Filter.Expression(Filter.ExpressionType.ISNULL, this.visit(ctx.identifier()));
		}

		@Override
		public Filter.Operand visitIsNotNullExpression(FiltersParser.IsNotNullExpressionContext ctx) {
			return new Filter.Expression(Filter.ExpressionType.ISNOTNULL, this.visit(ctx.identifier()));
		}

		private Filter.ExpressionType convertCompare(String compare) {
			if (!COMP_EXPRESSION_TYPE_MAP.containsKey(compare)) {
				throw new RuntimeException("Unknown compare operator: " + compare);
			}
			return COMP_EXPRESSION_TYPE_MAP.get(compare);
		}

		@Override
		public Filter.Operand visitAndExpression(FiltersParser.AndExpressionContext ctx) {
			return new Filter.Expression(Filter.ExpressionType.AND, this.visit(ctx.left), this.visit(ctx.right));
		}

		@Override
		public Filter.Operand visitOrExpression(FiltersParser.OrExpressionContext ctx) {
			return new Filter.Expression(Filter.ExpressionType.OR, this.visit(ctx.left), this.visit(ctx.right));
		}

		@Override
		public Filter.Operand visitGroupExpression(FiltersParser.GroupExpressionContext ctx) {
			return new Filter.Group(castToExpression(this.visit(ctx.booleanExpression())));
		}

View on GitHub (pinned to 98a7beda4f)

Solutions

  1. Correct the operator token in the filter expression text to one supported by the DSL: ==, != (also <>), >, >=, <, <=, IN, NIN, NOT, AND, OR
  2. Print/inspect the full filter string; the message appends the offending token so you can locate it
  3. If building filter strings programmatically, prefer constructing Filter.Expression objects directly instead of string parsing
  4. Wrap parse() in try-catch and surface a user-facing validation error with the bad operator

Example fix

// before
parser.parse("price eq 10");
// after
parser.parse("price == 10");
Defensive patterns

Strategy: validation

Validate before calling

Set<String> supported = Set.of("==","!=",">",">=","<","<=","IN","NIN","AND","OR","NOT","ISNULL","ISNOTNULL");
// validate each operator token of the filter string against 'supported' before calling parse()

Try / catch

try { filter = new FilterExpressionTextParser().parse(text); }
catch (RuntimeException e) { throw new IllegalArgumentException("Bad filter operator: " + e.getMessage(), e); }

Prevention

When it happens

Trigger: Calling new FilterExpressionTextParser().parse("price ~~ 10") or any filter string whose operator token is misspelled or unsupported (e.g. '=', '===', 'eq', '!in'); the token fails the COMP_EXPRESSION_TYPE_MAP lookup in visitCompareExpression -> convertCompare.

Common situations: Typos in hand-written filter strings; copying filter syntax from another library (e.g. MongoDB or SQL syntax) that uses different operators; language-model-generated filter text using invented operators.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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