apache/druid · error · IllegalArgumentException

Detected duplicate prefix in join clauses

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.

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.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Detected conflicting prefixes in join clauses
• Cannot join lookup with condition referring to non-key…
• Cannot join lookup with non-equi condition
• Column[ ] is not a valid column for segment[ ]
• Column[ ] is not a valid column for the frame based…

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

Appendix: 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)