{"record":{"id":"a73407a33497378d","repo":"apache/skywalking","slug":"hierarchy-definition-yml-hierarchy-layer-layer","errorCode":null,"errorMessage":"hierarchy-definition.yml hierarchy: {layer} layer-level should be greater than {lowerLayer} layer-level.","messagePattern":"hierarchy-definition\\.yml hierarchy: (.+?) layer-level should be greater than (.+?) layer-level\\.","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":209,"sourceCode":"                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) {\n            this.name = name;\n            this.expression = expression;\n            this.matcher = matcher;\n        }","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java#L191-L227","documentation":"HierarchyDefinitionService enforces a strict monotonic ordering: a parent layer's numeric level must be strictly greater than every lower layer's level ('if (layerLevel <= lowerLayerLevel)' throws). This keeps layer hierarchy comparisons well-defined (e.g. service hierarchy resolution in UI and query). It is a config-consistency check executed at OAP startup, immediately after the missing-level checks.","triggerScenarios":"OAP boot parses hierarchy-definition.yml; both layers have valid 'layer-levels:' entries, but the parent layer's level is less than or equal to a lower layer declared under its 'hierarchy:' mapping.","commonSituations":"Hand-editing levels and inverting the intended order; adding a new layer at a level that collides with (or exceeds) its parent; reusing the same level number for parent and child after a refactor.","solutions":["Edit hierarchy-definition.yml and raise the parent layer's level (or lower the child's) so parent > child strictly — equal values are also rejected.","Review the whole chain: if the child is itself a parent of deeper layers, every transitive level must remain strictly decreasing downward.","Restart OAP to re-run validation."],"exampleFix":"# before\nlayer-levels:\n  MCP_GATEWAY: 1\n  NODE_JS: 2\nhierarchy:\n  MCP_GATEWAY:\n    NODE_JS: {}\n\n# after\nlayer-levels:\n  MCP_GATEWAY: 2\n  NODE_JS: 1\nhierarchy:\n  MCP_GATEWAY:\n    NODE_JS: {}","handlingStrategy":"validation","validationCode":"// Before boot: enforce strict downward monotonicity\nfor (Map.Entry<String, Map<String, ?>> e : hierarchy.entrySet()) {\n    int parent = levels.get(e.getKey());\n    for (String lower : e.getValue().keySet()) {\n        if (parent <= levels.get(lower)) {\n            throw new ConfigException(e.getKey() + \" level must be > \" + lower + \" level\");\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"Not applicable — startup-time config failure; correct the YAML levels.","preventionTips":["Number levels with gaps (e.g. 100, 90, 80) so insertions don't force renumbering.","Add a CI schema check that hierarchy levels strictly decrease along every parent→child path.","Document the intended layer order next to the file."],"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"}