{"record":{"id":"2fa405f8a147fa11","repo":"apache/druid","slug":"encountered-an-unknown-partialloadmatcher-type-in","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"server/src/main/java/org/apache/druid/server/coordinator/rules/UnknownPartialLoadMatcher.java","lineNumber":52,"sourceCode":" * lifetime to surface the configuration mismatch without flooding the logs across coordinator passes.\n * <p>\n * Note: this matcher is not lossless to round-trip. An older coordinator that reads a rule with an unknown matcher\n * type and then re-serializes it will not preserve the original {@code type} discriminator or any matcher-specific\n * configuration. The expected operational pattern is to upgrade the coordinator to a version that recognizes the\n * matcher rather than rely on round-trip.\n */\npublic class UnknownPartialLoadMatcher implements PartialLoadMatcher\n{\n  private static final Logger log = new Logger(UnknownPartialLoadMatcher.class);\n\n  private final AtomicBoolean warned = new AtomicBoolean(false);\n\n  @Override\n  @Nullable\n  public MatchResult match(DataSegment segment, Map<String, Object> baseLoadSpec)\n  {\n    if (warned.compareAndSet(false, true)) {\n      log.warn(\n          \"Encountered an unknown PartialLoadMatcher type in a partial load rule. The matcher will be treated as\"\n          + \" not applicable; the rule's onCannotMatch behavior determines the outcome. Upgrade Druid to a version\"\n          + \" that supports this matcher.\"\n      );\n    }\n    return null;\n  }\n\n  @Override\n  public boolean equals(Object o)\n  {\n    return o instanceof UnknownPartialLoadMatcher;\n  }\n\n  @Override\n  public int hashCode()\n  {\n    return UnknownPartialLoadMatcher.class.hashCode();","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/server/src/main/java/org/apache/druid/server/coordinator/rules/UnknownPartialLoadMatcher.java#L34-L70","documentation":"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.","triggerScenarios":"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.","commonSituations":"Rolling upgrades where rules are created on a newer cluster before coordinators are upgraded; copying rule JSON between clusters of different versions.","solutions":["Upgrade Druid coordinators (and the whole cluster) to a version that supports the matcher type","Inspect the rule JSON (`GET /druid/coordinator/v1/rules`) and rewrite the rule using matcher types supported by the current version","Temporarily set the rule's onCannotMatch to a safe behavior (e.g. keep/load) until upgraded"],"exampleFix":"// before\n{\"type\":\"someFutureMatcher\",\"...\":\"...\"}\n// after (supported on current version)\n{\"type\":\"intervalMatch\",\"interval\":\"2026-01-01/2026-02-01\"}","handlingStrategy":"fallback","validationCode":"final Set<String> supported = Set.of(\"timePeriod\", \"interval\", ...); boolean known = supported.contains(ruleMatcherJson.path(\"type\").asText());","typeGuard":"boolean isKnownMatcherType(JsonNode matcher, Set<String> knownTypes) { return matcher != null && knownTypes.contains(matcher.path(\"type\").asText()); }","tryCatchPattern":"try { evaluateRule(rule, segment); } catch (UnknownMatcherException e) { LOG.warn(\"Rule {} has unknown matcher; using onCannotMatch\", rule.getId()); applyOnCannotMatch(rule, segment); }","preventionTips":["Upgrade coordinators before creating rules from newer Druid UIs/APIs","Pin rule creation tooling to matcher types documented for your cluster version","After upgrades, re-save rules so unknown types are validated"],"tags":["coordinator","rules","version-compat","load-rules"],"backgroundTag":"unsupported-enum-value","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}