apache/skywalking · error · IllegalStateException

HierarchyRuleProvider did not produce a matcher for rule: {e

Error message

HierarchyRuleProvider did not produce a matcher for rule: {entry.getKey()}

What it means

After HierarchyDefinitionService hands the auto-matching-rules expressions to the HierarchyRuleProvider for compilation, it expects a matcher (BiFunction) for every rule name in the YAML. This IllegalStateException fires when builtRules lacks an entry for a rule — the provider silently skipped compilation (typically an unparseable expression) rather than failing itself.

Source

Thrown at oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java:170

            // snakeyaml's bean binding discards them, so the rule lines must be read separately.
            // Same idiom as every other rule loader in the DSL path (Rules, LALConfigs,
            // ZabbixConfigs): read the bytes once, decode as UTF-8 explicitly.
            final String yamlText = new String(
                ResourceUtils.readToStream("hierarchy-definition.yml").readAllBytes(), UTF_8);
            final Yaml yaml = new Yaml();
            final Map<String, Map> config = yaml.loadAs(yamlText, Map.class);
            final Map<String, Map<String, String>> hierarchy = (Map<String, Map<String, String>>) config.get("hierarchy");
            final Map<String, String> ruleExpressions = (Map<String, String>) config.get("auto-matching-rules");
            this.layerLevels = (Map<String, Integer>) config.get("layer-levels");

            final Map<String, BiFunction<Service, Service, Boolean>> builtRules = ruleProvider.buildRules(
                ruleExpressions,
                DslYamlLineIndex.keyLines(yamlText, "auto-matching-rules"));

            this.matchingRules = ruleExpressions.entrySet().stream().map(entry -> {
                final BiFunction<Service, Service, Boolean> matcher = builtRules.get(entry.getKey());
                if (matcher == null) {
                    throw new IllegalStateException(
                        "HierarchyRuleProvider did not produce a matcher for rule: " + entry.getKey());
                }
                final MatchingRule matchingRule = new MatchingRule(entry.getKey(), entry.getValue(), matcher);
                return Map.entry(entry.getKey(), matchingRule);
            }).collect(toMap(Map.Entry::getKey, Map.Entry::getValue));
            hierarchy.forEach((layer, lowerLayers) -> {
                final Map<String, MatchingRule> rules = new HashMap<>();
                lowerLayers.forEach((lowerLayer, ruleName) -> {
                    rules.put(lowerLayer, this.matchingRules.get(ruleName));
                });
                this.hierarchyDefinition.put(layer, rules);
            });
        } catch (IOException e) {
            throw new UnexpectedException("hierarchy-definition.yml not found.", e);
        }
    }

    private void checkLayers() {

View on GitHub (pinned to 102af09b4a)

Solutions

1. Check hierarchy-definition.yml's auto-matching-rules block and correct the named rule's expression to the supported grammar (see the provider's rule syntax docs)
2. Look for a preceding WARN/ERROR log from the rule provider explaining why compilation was skipped
3. Remove or comment out the offending rule if hierarchy auto-matching for that layer is not needed

Example fix

# before
auto-matching-rules:
  bad-rule: "service.name ==& 'gateway'"   # invalid operator
# after
auto-matching-rules:
  gateway-rule: "service.name == 'gateway'"

# validate every rule compiles before boot
Set<String> yamlRules = cfg.get('auto-matching-rules', {}).keySet()
Map<String, ?> built = ruleProvider.buildRules(cfg.get('auto-matching-rules'), lineIndex)
assert built.keySet().equals(yamlRules) : "uncompiled rules: " + (yamlRules - built.keySet())

Startup should fail fast (missing matcher means broken config); during development, catch IllegalStateException from the init path and print the offending rule name to pinpoint the YAML line.

When it happens

Trigger: hierarchy-definition.yml contains an auto-matching-rules entry whose expression the provider cannot compile (bad syntax, unsupported operator, missing expression fields), so the provider returns a map without that key.

Common situations: Writing custom hierarchy auto-matching rules with invalid expression syntax; upgrading OAP where the rule grammar changed and old expressions no longer compile; typos in rule expression strings.

Related errors

• hierarchy-definition.yml {layer} is not a valid layer name.
• hierarchy-definition.yml layer-levels: {layer} is not defin
• hierarchy-definition.yml layer-levels: {lowerLayer} is not
• hierarchy-definition.yml hierarchy: {layer} layer-level shou
• Component name [{name}] in Component-Server-Mappings doesn't

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/b52670facadd41c9. Report an issue: GitHub.