apache/skywalking · critical · IllegalStateException

No HierarchyRuleProvider found on classpath. Ensure the hier

Error message

No HierarchyRuleProvider found on classpath. Ensure the hierarchy analyzer module is included.

What it means

HierarchyDefinitionService supports auto-matching of service hierarchy layers via rules compiled by a HierarchyRuleProvider discovered through Java SPI (META-INF/services). If ServiceLoader finds no provider — i.e. the hierarchy analyzer module that registers CompiledHierarchyRuleProvider is not on the classpath — this IllegalStateException fails service initialization at OAP startup.

Source

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

            this.init(loadProvider());
            this.checkLayers();
        }
    }

    /**
     * Discovers a {@link HierarchyRuleProvider} via Java SPI. The provider is registered in
     * {@code META-INF/services/...HierarchyDefinitionService$HierarchyRuleProvider} by the
     * hierarchy analyzer module ({@code CompiledHierarchyRuleProvider}).
     * Takes the first provider found; fails fast if none is on the classpath.
     */
    private static HierarchyRuleProvider loadProvider() {
        final ServiceLoader<HierarchyRuleProvider> loader =
            ServiceLoader.load(HierarchyRuleProvider.class);
        for (final HierarchyRuleProvider provider : loader) {
            log.info("Using hierarchy rule provider: {}", provider.getClass().getName());
            return provider;
        }
        throw new IllegalStateException(
            "No HierarchyRuleProvider found on classpath. "
                + "Ensure the hierarchy analyzer module is included.");
    }

    @SuppressWarnings("unchecked")
    private void init(final HierarchyRuleProvider ruleProvider) {
        try {
            // Bind from the decoded text, then re-compose the SAME text for positional marks:
            // 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");

View on GitHub (pinned to 102af09b4a)

Solutions

Add the hierarchy analyzer module jar (the one registering CompiledHierarchyRuleProvider in META-INF/services) to the OAP classpath / dependencies
If using a custom starter, mirror server-starter's dependency list so all SPI-providing modules are present
For fat jars, use a shading 'ServicesResourceTransformer' so META-INF/services files merge instead of being overwritten

Example fix

<!-- before: server-core only -->
<dependency>
  <groupId>org.apache.skywalking</groupId>
  <artifactId>oap-server-core</artifactId>
</dependency>
<!-- after: include the module providing HierarchyRuleProvider -->
<dependency>
  <groupId>org.apache.skywalking</groupId>
  <artifactId>hierarchy-analyzer</artifactId>
  <version>${project.version}</version>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

// packaging self-check: SPI registration must be present
var url = getClass().getClassLoader().getResource("META-INF/services/org.apache.skywalking.oap.server.core.config.HierarchyDefinitionService$HierarchyRuleProvider");
if (url == null) throw new IllegalStateException("hierarchy analyzer module missing from packaging");

Try / catch

Fail fast at startup is correct; in custom starters, validate classpath contents during build (dependency:tree / artifact presence check) instead of catching at runtime.

Prevention

Base custom OAP packaging on server-starter's full dependency list
Use maven-shade ServicesResourceTransformer to merge META-INF/services in fat jars
Smoke-boot any custom distribution before deploying

When it happens

Trigger: Running a trimmed OAP distribution (e.g. server-tools/profile-exporter or a custom starter) that includes server-core's HierarchyDefinitionService but not the hierarchy analyzer module; a repackaged jar whose META-INF/services entries were lost by shading/merging.

Common situations: Custom OAP packaging that drops optional analyzer modules; fat-jar builds where ServiceLoader resource files from multiple jars overwrite each other; using a downstream project that embeds server-core without the full server-starter dependency set.

Related errors

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