{"record":{"id":"2f5692a94a703810","repo":"apache/skywalking","slug":"hierarchy-definition-yml-layer-levels-layer-is","errorCode":null,"errorMessage":"hierarchy-definition.yml  layer-levels: {layer} 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":198,"sourceCode":"                });\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()) {\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","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java#L180-L216","documentation":"checkLayers() also requires every layer participating in the hierarchy mapping to have an entry under layer-levels. When a layer appears as a key in the hierarchy block (or as a lowerLayer) but has no level defined, this IllegalArgumentException is thrown ('layer-levels: X is not defined'), because level ordering cannot be validated without it.","triggerScenarios":"hierarchy-definition.yml defines hierarchy: {MESH: {MESH_CP: rule}} but layer-levels lists MESH only, not MESH_CP; or a new lower layer is added to the hierarchy without a corresponding layer-levels entry.","commonSituations":"Editing the hierarchy section to add a new parent/child relationship while forgetting the level entry; inconsistent custom file after upgrading OAP when new layers were introduced upstream.","solutions":["Add the missing layer to layer-levels with an integer level (the exception message names the exact layer)","Ensure every layer key and every lower-layer key in the hierarchy block has a layer-levels entry","Keep level ordering consistent: a parent layer's level must be greater than its lower layers', or the follow-up check will fail"],"exampleFix":"# before\nlayer-levels:\n  MESH: 2\nhierarchy:\n  MESH:\n    MESH_CP: gateway-rule   # MESH_CP level missing\n# after\nlayer-levels:\n  MESH: 2\n  MESH_CP: 1\nhierarchy:\n  MESH:\n    MESH_CP: gateway-rule","handlingStrategy":"validation","validationCode":"Set<String> leveled = layerLevels.keySet();\nSet<String> referenced = new HashSet<>();\nhierarchyDefinition.forEach((l, lowers) -> { referenced.add(l); referenced.addAll(lowers.keySet()); });\nassert referenced.stream().allMatch(leveled::contains) : \"layers missing from layer-levels: \" + disjoint(referenced, leveled);","typeGuard":null,"tryCatchPattern":"Fail fast at startup; a hierarchy without levels cannot be order-validated, so catching would produce an inconsistent service topology view.","preventionTips":["Whenever you add a layer to the hierarchy block, immediately add its layer-levels entry — treat the two sections as one unit","Use a YAML schema check (every hierarchy layer and lower-layer key must appear in layer-levels) in CI","Remember the follow-up rule: parent level must exceed child level, so plan integer levels top-down"],"tags":["hierarchy","configuration","yaml","layer","startup","validation"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}