apache/druid · error · IllegalArgumentException

Cannot handle constant condition: %s

Error message

Cannot handle constant condition: %s

What it means

MSQ's sort-merge join only supports equi-join conditions that are neither always-true nor always-false and contain no non-equi predicates. validateCondition rejects a constant FALSE condition (and separately non-equi conditions) because the merge algorithm cannot evaluate such a join. Always-true conditions (cross join) are allowed through.

Source

Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/querykit/common/SortMergeJoinStageProcessor.java:267

        retVal.add(i);
      }
    }

    return retVal.toArray(new int[0]);
  }

  /**
   * Validates that a join condition can be handled by this processor. Returns the condition if it can be handled.
   * Throws {@link IllegalArgumentException} if the condition cannot be handled.
   */
  public static JoinConditionAnalysis validateCondition(final JoinConditionAnalysis condition)
  {
    if (condition.isAlwaysTrue()) {
      return condition;
    }

    if (condition.isAlwaysFalse()) {
      throw new IAE("Cannot handle constant condition: %s", condition.getOriginalExpression());
    }

    if (condition.getNonEquiConditions().size() > 0) {
      throw new IAE("Cannot handle non-equijoin condition: %s", condition.getOriginalExpression());
    }

    if (condition.getEquiConditions().stream().anyMatch(c -> !c.getLeftExpr().isIdentifier())) {
      throw new IAE(
          "Cannot handle equality condition involving left-hand expression: %s",
          condition.getOriginalExpression()
      );
    }

    return condition;
  }

  /**
   * Validates that all signatures from {@link #collectAndReadPartitions(ExecutionContext)} are prefixed by the

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Fix the SQL so the ON clause is a real equi-condition on join columns (e.g. a.k = b.k)
2. Remove contradictory literal predicates from the ON clause; if a cross join is intended, use ON TRUE or a comma join
3. Move non-equi conditions (e.g. a.start < b.end) to the WHERE clause or restructure as an equi-join plus filter
4. Run the query on the native engine if a range/non-equi join is truly required

Example fix

// before
SELECT * FROM a JOIN b ON a.k = b.k AND 1 = 0
// after
SELECT * FROM a JOIN b ON a.k = b.k

// Validate ON clause before running on MSQ
JoinConditionAnalysis cond = JoinConditionAnalysis.forExpression(onExpr, "j", exprParser);
if (cond.isAlwaysFalse()) {
  throw new IllegalArgumentException("MSQ sort-merge join cannot handle always-false ON: " + onExpr);
}
if (!cond.getNonEquiConditions().isEmpty()) {
  throw new IllegalArgumentException("Only equi-joins are supported by MSQ: " + onExpr);
}

try {
  runMsqQuery(query);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Cannot handle")) {
    // rewrite SQL to an equi-join or route to the native engine
  }
}

When it happens

Trigger: A JOIN whose ON clause evaluates to a constant false (e.g. ON 1=0, or conflicting literal predicates like ON a.k = b.k AND 1 = 2), reaching SortMergeJoinStageProcessor construction; or an ON clause with non-equi predicates like a.k < b.k.

Common situations: Dynamically generated SQL where filters collapse the ON clause to FALSE; hand-written joins with inequality predicates (range joins) assumed to be supported by MSQ; optimizer passthrough of contradictory conditions.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Cannot handle non-equijoin condition: %s
• Cannot handle equality condition involving left-hand express
• Unknown
• Number of partitions not known for [%s].
• Shuffle of kind [%s] cannot generate partition boundaries fo

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/3033cef543adca8f. Report an issue: GitHub.