apache/druid · error · IllegalArgumentException

Detected duplicate prefix in join clauses: [%s]

Error message

Detected duplicate prefix in join clauses: [%s]

What it means

JoinPrefixUtils.checkPrefixesForDuplicatesAndShadowing validates the set of prefixes used by join clauses before a query runs. Two joinable tables must not use the identical prefix because column references would be ambiguous, so an exact duplicate triggers this IllegalArgumentException.

Source

Thrown at processing/src/main/java/org/apache/druid/segment/join/JoinPrefixUtils.java:93

  /**
   * Check if any prefixes in the provided list duplicate or shadow each other.
   *
   * @param prefixes A mutable list containing the prefixes to check. This list will be sorted by descending
   *                 string length.
   */
  public static void checkPrefixesForDuplicatesAndShadowing(
      final List<String> prefixes
  )
  {
    // this is a naive approach that assumes we'll typically handle only a small number of prefixes
    prefixes.sort(DESCENDING_LENGTH_STRING_COMPARATOR);
    for (int i = 0; i < prefixes.size(); i++) {
      String prefix = prefixes.get(i);
      for (int k = i + 1; k < prefixes.size(); k++) {
        String otherPrefix = prefixes.get(k);
        if (prefix.equals(otherPrefix)) {
          throw new IAE("Detected duplicate prefix in join clauses: [%s]", prefix);
        }
        if (isPrefixedBy(prefix, otherPrefix)) {
          throw new IAE("Detected conflicting prefixes in join clauses: [%s, %s]", prefix, otherPrefix);
        }
      }
    }
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Rename one join's prefix so every join in the query has a distinct prefix (e.g. l1., l2., ...)
2. If the query is generated, ensure the generator assigns a unique prefix per joinable table
3. Search the native query JSON for duplicated 'prefix' fields and deduplicate

Example fix

// before
join prefixes: ["l1.", "l1."]
// after
join prefixes: ["l1.", "l2."]

Set<String> seen = new HashSet<>();
for (String p : prefixes) { if (!seen.add(p)) throw new IllegalArgumentException("duplicate prefix " + p); }
JoinPrefixUtils.checkPrefixesForDuplicatesAndShadowing(new ArrayList<>(prefixes));

try { checkPrefixes(...); } catch (IAE e) { throw new QueryPlanningException("duplicate join prefixes", e); }

When it happens

Trigger: Passing a list of prefixes to checkPrefixesForDuplicatesAndShadowing where two entries are equal strings, e.g. two lookup/broadcast joins both declared with prefix 'l1.' in the same native query.

Common situations: Hand-written native JSON with multiple joins that reuse the same prefix; programmatic query builders that auto-number prefixes incorrectly; copying a join clause and forgetting to change its prefix.

Related errors

• Detected conflicting prefixes in join clauses: [%s, %s]
• maxStringBytes must be greater than 0
• maxStringBytes must be greater than 0
• Column[%s] does not start with prefix[%s]
• Multiple joinable factories are valid for table[%s]

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