{"record":{"id":"0a5544b15900dac7","repo":"apache/skywalking","slug":"hierarchy-definition-yml-layer-is-not-a-valid-la","errorCode":null,"errorMessage":"hierarchy-definition.yml {layer} is not a valid layer name.","messagePattern":"hierarchy-definition\\.yml (.+?) is not a valid layer name\\.","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":191,"sourceCode":"                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()) {\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(","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java#L173-L209","documentation":"During startup, HierarchyDefinitionService.checkLayers() validates every key under layer-levels against the Layer enum via Layer.nameOf(); if the name resolves to Layer.UNDEFINED (not a known layer such as GENERAL, VIRTUAL_DATABASE, MESH, K8S, etc.), this IllegalArgumentException aborts boot, naming the bad layer.","triggerScenarios":"hierarchy-definition.yml's layer-levels contains a typo'd or unrecognized layer key, e.g. 'MESH_CP' or 'virtual-database' instead of an exact Layer enum name.","commonSituations":"Customizing layer levels without matching the Layer enum's exact names; upgrading OAP where layer names were added/renamed and the old custom file uses stale names.","solutions":["Compare the failing layer name against the Layer enum values in server-core and fix the spelling/case in layer-levels","After an OAP upgrade, re-diff your customized hierarchy-definition.yml against the shipped default to catch renamed layers","Remove entries for layers your deployment does not use instead of guessing names"],"exampleFix":"# before\nlayer-levels:\n  MESH_CONTROL_PLANE: 2   # not a Layer enum name\n# after\nlayer-levels:\n  MESH_CP: 2","handlingStrategy":"validation","validationCode":"// pre-boot layer name check\nfor (String layer : layerLevels.keySet()) {\n    if (Layer.nameOf(layer) == Layer.UNDEFINED) {\n        throw new IllegalArgumentException(\"Fix config: unknown layer \" + layer);\n    }\n}","typeGuard":"boolean isValidLayerName(String name) {\n    return Layer.nameOf(name) != Layer.UNDEFINED;\n}","tryCatchPattern":"Let it fail fast at startup; catching would boot with an unusable hierarchy definition.","preventionTips":["Derive layer names from the Layer enum (or its documented value list), never free-hand them","Re-diff customized hierarchy-definition.yml against the shipped default after each upgrade","Add a config-lint step for layer names in CI"],"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"}