prestodb/presto · error · UnsupportedOperationException

unsupported join criteria: %s

Error message

unsupported join criteria: %s

What it means

After handling JoinOn, JoinUsing, and (rejected earlier) NaturalJoin criteria, any other JoinCriteria implementation reaches an else branch that throws a plain UnsupportedOperationException naming the criteria class. This is an internal invariant violation rather than a SemanticException — the parser produced a criteria type the analyzer does not handle (e.g. a newly added criteria type without analyzer support).

Source

Thrown at presto-main-base/src/main/java/com/facebook/presto/sql/analyzer/StatementAnalyzer.java:3551

                    analysis.addCoercion(expression, BOOLEAN, false);
                }

                if (expression instanceof LogicalBinaryExpression) {
                    if (((LogicalBinaryExpression) expression).getOperator() == LogicalBinaryExpression.Operator.OR) {
                        String warningMessage = createWarningMessage(expression, "JOIN conditions with an OR can cause performance issues as it may lead to a cross join with filter");
                        warningCollector.add(new PrestoWarning(PERFORMANCE_WARNING, warningMessage));
                    }
                }

                verifyJoinOnConditionReferencesRelatedFields(left, right, expression, node.getRight());
                verifyNoAggregateWindowOrGroupingFunctions(analysis.getFunctionHandles(), functionAndTypeResolver, expression, "JOIN clause");

                analysis.recordSubqueries(node, expressionAnalysis);
                analysis.setJoinCriteria(node, expression);
                collectIndirectSources(expression, TransformationSubtype.JOIN);
            }
            else {
                throw new UnsupportedOperationException("unsupported join criteria: " + criteria.getClass().getName());
            }

            return output;
        }

        private void verifyJoinOnConditionReferencesRelatedFields(Scope leftScope, Scope rightScope, Expression expression, Relation rightRelation)
        {
            if (!isJoinOnConditionReferencesRelatedFields(expression, leftScope, rightScope)) {
                Optional<String> tableName = tryGetTableName(rightRelation);
                String warningMessage = tableName.isPresent() ?
                        createWarningMessage(
                                expression,
                                format(
                                        "JOIN ON condition(s) do not reference the joined table '%s' and other tables in the same " +
                                                "expression that can cause performance issues as it may lead to a cross join with filter",
                                        tableName.get())) :
                        createWarningMessage(
                                expression,

View on GitHub (pinned to 55bb57d202)

Solutions

1. Check the Presto version for a known bug matching the criteria class in the message and upgrade/downgrade accordingly
2. Rewrite the join using standard ON or USING syntax
3. File a bug with the query and criteria class name reported in the message

Example fix

-- before (unhandled criteria form)
SELECT * FROM a JOIN b ON <unsupported-criteria>
-- after
SELECT * FROM a JOIN b ON a.id = b.id

// Use only JOIN ... ON / JOIN ... USING forms; reject anything else
if (!Pattern.compile("\\bJOIN\\b(?!").matcher(sql).find()) { /* gate to standard joins */ }

try { stmt.execute(sql); } catch (SQLException e) {
    if (e.getMessage() != null && e.getMessage().contains("unsupported join criteria")) {
        throw new QueryBuildException("Analyzer cannot handle this join criteria class: " + e.getMessage(), e);
    } throw e;
}

When it happens

Trigger: A Join node whose criteria is a JoinCriteria subclass not covered by the analyzer's instanceof chain (new grammar feature or custom criteria type); usually surfaced only after parser extensions or version mismatches between parser and analyzer.

Common situations: Running a patched/extended Presto build where new join syntax was added to the parser but not the analyzer; bugs during Presto upgrades where grammar and analyzer are out of sync.

Related errors

• GENERIC_INTERNAL_ERROR
• GENERIC_INTERNAL_ERROR
• MISSING_ATTRIBUTE
• INVALID_TABLE_PROPERTY
• MISSING_ATTRIBUTE

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/b040c17004f78401. Report an issue: GitHub.