{"record":{"id":"3beba92fafe3a12b","repo":"apache/skywalking","slug":"hierarchy-definition-yml-not-found","errorCode":null,"errorMessage":"hierarchy-definition.yml not found.","messagePattern":"hierarchy-definition\\.yml not found\\.","errorType":"exception","errorClass":"UnexpectedException","httpStatus":null,"severity":"critical","filePath":"oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java","lineNumber":184,"sourceCode":"\n            this.matchingRules = ruleExpressions.entrySet().stream().map(entry -> {\n                final BiFunction<Service, Service, Boolean> matcher = builtRules.get(entry.getKey());\n                if (matcher == null) {\n                    throw new IllegalStateException(\n                        \"HierarchyRuleProvider did not produce a matcher for rule: \" + entry.getKey());\n                }\n                final MatchingRule matchingRule = new MatchingRule(entry.getKey(), entry.getValue(), matcher);\n                return Map.entry(entry.getKey(), matchingRule);\n            }).collect(toMap(Map.Entry::getKey, Map.Entry::getValue));\n            hierarchy.forEach((layer, lowerLayers) -> {\n                final Map<String, MatchingRule> rules = new HashMap<>();\n                lowerLayers.forEach((lowerLayer, ruleName) -> {\n                    rules.put(lowerLayer, this.matchingRules.get(ruleName));\n                });\n                this.hierarchyDefinition.put(layer, rules);\n            });\n        } catch (IOException e) {\n            throw new UnexpectedException(\"hierarchy-definition.yml not found.\", e);\n        }\n    }\n\n    private void checkLayers() {\n        this.layerLevels.keySet().forEach(layer -> {\n            if (Layer.nameOf(layer).equals(Layer.UNDEFINED)) {\n                throw new IllegalArgumentException(\n                    \"hierarchy-definition.yml \" + layer + \" is not a valid layer name.\");\n            }\n        });\n        this.hierarchyDefinition.forEach((layer, lowerLayers) -> {\n            final Integer layerLevel = this.layerLevels.get(layer);\n            if (this.layerLevels.get(layer) == null) {\n                throw new IllegalArgumentException(\n                    \"hierarchy-definition.yml  layer-levels: \" + layer + \" is not defined\");\n            }\n\n            for (final String lowerLayer : lowerLayers.keySet()) {","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java#L166-L202","documentation":"HierarchyDefinitionService.init() reads hierarchy-definition.yml (rule text plus DslYamlLineIndex source lines). Any IOException while locating or reading the file is wrapped in this UnexpectedException. Despite the message saying 'not found', it covers all read failures — missing file, unreadable path, or closed stream.","triggerScenarios":"The hierarchy-definition.yml configured path does not exist in the OAP distribution; the file exists but the OAP process lacks read permission; the config directory was altered in a custom Docker image.","commonSituations":"Custom Docker images or Helm charts that copy only application.yml and drop other resource files; setting a custom hierarchy definition path that was never created; filesystem permission issues in containerized deployments.","solutions":["Verify the hierarchy-definition.yml path exists and is readable by the OAP user (check the exception's wrapped cause for the exact path)","Restore the file from the official distribution or your config management if it was deleted","In custom images, ensure COPY of the full config directory, not just application.yml"],"exampleFix":"# Dockerfile — before\nCOPY config/application.yml /skywalking/oap-libs/../config/\n# after — copy the whole config dir including hierarchy-definition.yml\nCOPY config/ /skywalking/config/","handlingStrategy":"validation","validationCode":"Path p = Path.of(configPath, \"hierarchy-definition.yml\");\nif (!Files.isReadable(p)) {\n    throw new IllegalStateException(\"Missing/unreadable hierarchy config: \" + p.toAbsolutePath());\n}","typeGuard":null,"tryCatchPattern":"Catch the UnexpectedException only at deployment tooling level to print the wrapped IOException cause (exact missing path); the OAP itself should keep failing fast.","preventionTips":["In Dockerfiles copy the entire config directory, not individual files","Add a container entrypoint check that all referenced config files exist before exec'ing the OAP","Mount custom config directories read-only at the documented path"],"tags":["hierarchy","configuration","file-io","startup","deployment"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}