quarkusio/quarkus · error · TemplateException

Not a legal operator:

Error message

Not a legal operator: 

What it means

Qute's {when}/switch-style sections support a fixed set of binary operators (==, !=, <, >, <=, >=, in, not in). When the parser produced an operator enum value that has no evaluation branch, WhenSectionHelper.Operator.evaluate() throws TemplateException. It indicates an unhandled/unsupported operator reached the evaluation stage.

Source

Thrown at independent-projects/qute/core/src/main/java/io/quarkus/qute/WhenSectionHelper.java:254

        }

        boolean evaluate(Object value, List<?> params) {
            switch (this) {
                case EQ:
                    return Objects.equals(value, params.get(0));
                case NE:
                    return !Objects.equals(value, params.get(0));
                case GE:
                case GT:
                case LE:
                case LT:
                    return compare(value, params.get(0));
                case IN:
                    return params.contains(value);
                case NOT_IN:
                    return !params.contains(value);
                default:
                    throw new TemplateException("Not a legal operator: " + this);
            }
        }

        @SuppressWarnings({ "rawtypes", "unchecked" })
        boolean compare(Object op1, Object op2) {
            if (op1 == null || op2 == null) {
                throw new TemplateException("Unable to compare null operands [op1=" + op1 + ", op2=" + op2 + "]");
            }
            Comparable c1;
            Comparable c2;
            if (op1 instanceof Comparable && op1.getClass().equals(op2.getClass())) {
                c1 = (Comparable) op1;
                c2 = (Comparable) op2;
            } else {
                c1 = Operator.getDecimal(op1);
                c2 = Operator.getDecimal(op2);
            }
            int result = c1.compareTo(c2);

View on GitHub (pinned to e1c734241f)

Solutions

1. Upgrade qute-core (io.quarkus.qute) so runtime and template compiler versions match — mismatched versions are the most common cause.
2. Inspect the template expression that produced the operator and replace it with a supported one (==, !=, <, >, <=, >=, in, not in).
3. If building expressions programmatically, only pass operators from WhenSectionHelper.Operator's supported set.
4. If you maintain a fork and added an operator, add a corresponding case in evaluate().

Example fix

// before (unsupported/unknown operator)
{#when myValue is 'x'}...{/} // invalid operator syntax
// after
{#when myValue}
  {#is eq 'x'}...{/}
{/}

Set<String> supported = Set.of("eq","ne","lt","le","gt","ge","in","not in","is");
if (!supported.contains(operator.trim())) throw new IllegalArgumentException("Unsupported operator: " + operator);

try {
    renderTemplate(tpl);
} catch (TemplateException e) {
    if (e.getMessage().startsWith("Not a legal operator")) {
        // fix template expression / align qute versions
    }
}

When it happens

Trigger: Evaluating a {when} / {if} condition whose operator is a Qute operator enum value with no case in the evaluate() switch (e.g. a new/internal operator used without an evaluation branch, or programmatic template building inserting an unexpected Operator).

Common situations: Programmatic template/section construction using internal APIs; running a template built on a newer Qute version against an older runtime where the operator enum gained new members; typos in custom section code reusing Operator enums.

Related errors

• Not a short-circuiting operator:
• Invalid template link [${templateLink}] - Expeting a link th
• Templates that are not backed by a file must provide extensi
• Literal must not be null
• Expression is not a literal:

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/e8bc0fc4bf213874. Report an issue: GitHub.