apache/druid · warning

Encountered an unknown PartialLoadMatcher type in a partial…

Error message

Encountered an unknown PartialLoadMatcher type in a partial load rule. The matcher will be treated as not applicable; the rule's onCannotMatch behavior determines the outcome. Upgrade Druid to a version that supports this matcher.

What it means

UnknownPartialLoadMatcher is the version-tolerant fallback for PartialLoadMatcher subtypes a coordinator doesn't recognize (rules written on a newer Druid). match() logs this warning once per matcher and returns null so the rule's onCannotMatch behavior decides the outcome. The cluster cannot evaluate the matcher, so results may differ from the rule author's intent.

Solutions

1. Upgrade Druid coordinators (and the whole cluster) to a version that supports the matcher type
2. Inspect the rule JSON (`GET /druid/coordinator/v1/rules`) and rewrite the rule using matcher types supported by the current version
3. Temporarily set the rule's onCannotMatch to a safe behavior (e.g. keep/load) until upgraded

Example fix

// before
{"type":"someFutureMatcher","...":"..."}
// after (supported on current version)
{"type":"intervalMatch","interval":"2026-01-01/2026-02-01"}

final Set<String> supported = Set.of("timePeriod", "interval", ...); boolean known = supported.contains(ruleMatcherJson.path("type").asText());

boolean isKnownMatcherType(JsonNode matcher, Set<String> knownTypes) { return matcher != null && knownTypes.contains(matcher.path("type").asText()); }

try { evaluateRule(rule, segment); } catch (UnknownMatcherException e) { LOG.warn("Rule {} has unknown matcher; using onCannotMatch", rule.getId()); applyOnCannotMatch(rule, segment); }

When it happens

Trigger: A partial load rule containing a PartialLoadMatcher JSON whose 'type' has no registered parser/implementation on this coordinator version; match() is called during coordinator rule evaluation for a segment.

Common situations: Rolling upgrades where rules are created on a newer cluster before coordinators are upgraded; copying rule JSON between clusters of different versions.

Related errors

• Cluster-level rules cannot be empty.
• datasource[ ] not found
• 'druid.coordinator.kill.maxSegments
• 'druid.coordinator.kill.period
• 'druid.coordinator.kill.

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

Appendix: source

Thrown at server/src/main/java/org/apache/druid/server/coordinator/rules/UnknownPartialLoadMatcher.java:52

 * lifetime to surface the configuration mismatch without flooding the logs across coordinator passes.
 * <p>
 * Note: this matcher is not lossless to round-trip. An older coordinator that reads a rule with an unknown matcher
 * type and then re-serializes it will not preserve the original {@code type} discriminator or any matcher-specific
 * configuration. The expected operational pattern is to upgrade the coordinator to a version that recognizes the
 * matcher rather than rely on round-trip.
 */
public class UnknownPartialLoadMatcher implements PartialLoadMatcher
{
  private static final Logger log = new Logger(UnknownPartialLoadMatcher.class);

  private final AtomicBoolean warned = new AtomicBoolean(false);

  @Override
  @Nullable
  public MatchResult match(DataSegment segment, Map<String, Object> baseLoadSpec)
  {
    if (warned.compareAndSet(false, true)) {
      log.warn(
          "Encountered an unknown PartialLoadMatcher type in a partial load rule. The matcher will be treated as"
          + " not applicable; the rule's onCannotMatch behavior determines the outcome. Upgrade Druid to a version"
          + " that supports this matcher."
      );
    }
    return null;
  }

  @Override
  public boolean equals(Object o)
  {
    return o instanceof UnknownPartialLoadMatcher;
  }

  @Override
  public int hashCode()
  {
    return UnknownPartialLoadMatcher.class.hashCode();

View on GitHub (pinned to 9b90983fd2)