{"record":{"id":"72b24ab5b0a7ce23","repo":"apache/skywalking","slug":"no-hierarchyruleprovider-found-on-classpath-ensur","errorCode":null,"errorMessage":"No HierarchyRuleProvider found on classpath. Ensure the hierarchy analyzer module is included.","messagePattern":"No HierarchyRuleProvider found on classpath\\. Ensure the hierarchy analyzer module is included\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java","lineNumber":143,"sourceCode":"            this.init(loadProvider());\n            this.checkLayers();\n        }\n    }\n\n    /**\n     * Discovers a {@link HierarchyRuleProvider} via Java SPI. The provider is registered in\n     * {@code META-INF/services/...HierarchyDefinitionService$HierarchyRuleProvider} by the\n     * hierarchy analyzer module ({@code CompiledHierarchyRuleProvider}).\n     * Takes the first provider found; fails fast if none is on the classpath.\n     */\n    private static HierarchyRuleProvider loadProvider() {\n        final ServiceLoader<HierarchyRuleProvider> loader =\n            ServiceLoader.load(HierarchyRuleProvider.class);\n        for (final HierarchyRuleProvider provider : loader) {\n            log.info(\"Using hierarchy rule provider: {}\", provider.getClass().getName());\n            return provider;\n        }\n        throw new IllegalStateException(\n            \"No HierarchyRuleProvider found on classpath. \"\n                + \"Ensure the hierarchy analyzer module is included.\");\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private void init(final HierarchyRuleProvider ruleProvider) {\n        try {\n            // Bind from the decoded text, then re-compose the SAME text for positional marks:\n            // snakeyaml's bean binding discards them, so the rule lines must be read separately.\n            // Same idiom as every other rule loader in the DSL path (Rules, LALConfigs,\n            // ZabbixConfigs): read the bytes once, decode as UTF-8 explicitly.\n            final String yamlText = new String(\n                ResourceUtils.readToStream(\"hierarchy-definition.yml\").readAllBytes(), UTF_8);\n            final Yaml yaml = new Yaml();\n            final Map<String, Map> config = yaml.loadAs(yamlText, Map.class);\n            final Map<String, Map<String, String>> hierarchy = (Map<String, Map<String, String>>) config.get(\"hierarchy\");\n            final Map<String, String> ruleExpressions = (Map<String, String>) config.get(\"auto-matching-rules\");\n            this.layerLevels = (Map<String, Integer>) config.get(\"layer-levels\");","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java#L125-L161","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"<!-- before: server-core only -->\n<dependency>\n  <groupId>org.apache.skywalking</groupId>\n  <artifactId>oap-server-core</artifactId>\n</dependency>\n<!-- after: include the module providing HierarchyRuleProvider -->\n<dependency>\n  <groupId>org.apache.skywalking</groupId>\n  <artifactId>hierarchy-analyzer</artifactId>\n  <version>${project.version}</version>\n</dependency>","handlingStrategy":"validation","validationCode":"// packaging self-check: SPI registration must be present\nvar url = getClass().getClassLoader().getResource(\"META-INF/services/org.apache.skywalking.oap.server.core.config.HierarchyDefinitionService$HierarchyRuleProvider\");\nif (url == null) throw new IllegalStateException(\"hierarchy analyzer module missing from packaging\");","typeGuard":null,"tryCatchPattern":"Fail fast at startup is correct; in custom starters, validate classpath contents during build (dependency:tree / artifact presence check) instead of catching at runtime.","preventionTips":["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"],"tags":["spi","classpath","hierarchy","startup","packaging"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}