{"record":{"id":"70d1ab6f394b526b","repo":"apache/skywalking","slug":"hierarchy-definition-yml-layer-levels-lowerlaye","errorCode":null,"errorMessage":"hierarchy-definition.yml  layer-levels: {lowerLayer} is not defined.","messagePattern":"hierarchy-definition\\.yml  layer-levels: (.+?) is not defined\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java","lineNumber":205,"sourceCode":"\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()) {\n                final Integer lowerLayerLevel = this.layerLevels.get(lowerLayer);\n                if (lowerLayerLevel == null) {\n                    throw new IllegalArgumentException(\n                        \"hierarchy-definition.yml  layer-levels: \" + lowerLayer + \" is not defined.\");\n                }\n                if (layerLevel <= lowerLayerLevel) {\n                    throw new IllegalArgumentException(\n                        \"hierarchy-definition.yml hierarchy: \" + layer + \" layer-level should be greater than \" + lowerLayer + \" layer-level.\");\n                }\n            }\n        });\n    }\n\n    @Getter\n    public static class MatchingRule {\n        private final String name;\n        private final String expression;\n        private final BiFunction<Service, Service, Boolean> matcher;\n\n        public MatchingRule(final String name, final String expression,\n                            final BiFunction<Service, Service, Boolean> matcher) {","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java#L187-L223","documentation":"HierarchyDefinitionService validates hierarchy-definition.yml after loading it: every layer that appears either as a key or as a lower-layer entry under 'hierarchy:' must have an explicit numeric entry under 'layer-levels:'. This error is thrown while iterating the hierarchy map when a referenced lower layer has no corresponding layer-levels entry. It fails fast at OAP startup so an inconsistent hierarchy config never reaches metric aggregation.","triggerScenarios":"OAP boot parses hierarchy-definition.yml; a layer name listed inside another layer's 'hierarchy:' mapping (lowerLayers.keySet()) has no matching key in the 'layer-levels:' block of the same file.","commonSituations":"Adding a new layer (e.g. MESH, MYSQL) to 'hierarchy:' but forgetting to declare its level; renaming a layer in one section but not the other; typos/case mismatch between 'hierarchy:' keys and 'layer-levels:' keys; copy-pasting a hierarchy block from another config that references layers this deployment does not define.","solutions":["Open hierarchy-definition.yml and find the lower layer named in the message inside the 'hierarchy:' section; add it to 'layer-levels:' with a level lower than the parent layer's.","Check for typos and exact case: layer names are matched as plain strings (this.layerLevels.get(lowerLayer) returns null on any mismatch).","If the layer should not participate in the hierarchy, remove its entry from the parent's 'hierarchy:' mapping instead of adding a level.","After editing, restart OAP and confirm the validation passes (no IllegalArgumentException in startup logs)."],"exampleFix":"# hierarchy-definition.yml — before\nlayer-levels:\n  MCP_GATEWAY: 2\n  GENERAL_ALS: 1\nhierarchy:\n  MCP_GATEWAY:\n    NODE_JS: {}\n\n# after (NODE_JS was missing a level)\nlayer-levels:\n  MCP_GATEWAY: 2\n  GENERAL_ALS: 1\n  NODE_JS: 0\nhierarchy:\n  MCP_GATEWAY:\n    NODE_JS: {}","handlingStrategy":"validation","validationCode":"// Validate hierarchy-definition.yml before boot\nMap<String, Integer> levels = loadLayerLevels(yaml);\nfor (String layer : yaml.hierarchyKeys()) {\n    Integer lvl = levels.get(layer);\n    if (lvl == null) throw new ConfigException(\"layer-levels missing: \" + layer);\n    for (String lower : yaml.lowerLayersOf(layer)) {\n        if (levels.get(lower) == null) {\n            throw new ConfigException(\"layer-levels missing: \" + lower);\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"Not applicable — thrown once at OAP startup; fix the YAML instead of catching.","preventionTips":["Lint hierarchy-definition.yml in CI: assert every layer referenced under 'hierarchy:' has a 'layer-levels:' entry.","Treat layer names as case-sensitive enums; avoid free-typing them.","After any layer change, boot a local OAP before deploying."],"tags":["configuration","startup","hierarchy","yaml","validation"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}