apache/skywalking · critical · IllegalArgumentException

hierarchy-definition.yml {layer} is not a valid layer name.

Error message

hierarchy-definition.yml {layer} is not a valid layer name.

What it means

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.

Source

Thrown at oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/HierarchyDefinitionService.java:191

                final MatchingRule matchingRule = new MatchingRule(entry.getKey(), entry.getValue(), matcher);
                return Map.entry(entry.getKey(), matchingRule);
            }).collect(toMap(Map.Entry::getKey, Map.Entry::getValue));
            hierarchy.forEach((layer, lowerLayers) -> {
                final Map<String, MatchingRule> rules = new HashMap<>();
                lowerLayers.forEach((lowerLayer, ruleName) -> {
                    rules.put(lowerLayer, this.matchingRules.get(ruleName));
                });
                this.hierarchyDefinition.put(layer, rules);
            });
        } catch (IOException e) {
            throw new UnexpectedException("hierarchy-definition.yml not found.", e);
        }
    }

    private void checkLayers() {
        this.layerLevels.keySet().forEach(layer -> {
            if (Layer.nameOf(layer).equals(Layer.UNDEFINED)) {
                throw new IllegalArgumentException(
                    "hierarchy-definition.yml " + layer + " is not a valid layer name.");
            }
        });
        this.hierarchyDefinition.forEach((layer, lowerLayers) -> {
            final Integer layerLevel = this.layerLevels.get(layer);
            if (this.layerLevels.get(layer) == null) {
                throw new IllegalArgumentException(
                    "hierarchy-definition.yml  layer-levels: " + layer + " is not defined");
            }

            for (final String lowerLayer : lowerLayers.keySet()) {
                final Integer lowerLayerLevel = this.layerLevels.get(lowerLayer);
                if (lowerLayerLevel == null) {
                    throw new IllegalArgumentException(
                        "hierarchy-definition.yml  layer-levels: " + lowerLayer + " is not defined.");
                }
                if (layerLevel <= lowerLayerLevel) {
                    throw new IllegalArgumentException(

View on GitHub (pinned to 102af09b4a)

Solutions

1. Compare the failing layer name against the Layer enum values in server-core and fix the spelling/case in layer-levels
2. After an OAP upgrade, re-diff your customized hierarchy-definition.yml against the shipped default to catch renamed layers
3. Remove entries for layers your deployment does not use instead of guessing names

Example fix

# before
layer-levels:
  MESH_CONTROL_PLANE: 2   # not a Layer enum name
# after
layer-levels:
  MESH_CP: 2

// pre-boot layer name check
for (String layer : layerLevels.keySet()) {
    if (Layer.nameOf(layer) == Layer.UNDEFINED) {
        throw new IllegalArgumentException("Fix config: unknown layer " + layer);
    }
}

boolean isValidLayerName(String name) {
    return Layer.nameOf(name) != Layer.UNDEFINED;
}

Let it fail fast at startup; catching would boot with an unusable hierarchy definition.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• hierarchy-definition.yml layer-levels: {layer} is not defin
• hierarchy-definition.yml layer-levels: {lowerLayer} is not
• hierarchy-definition.yml hierarchy: {layer} layer-level shou
• HierarchyRuleProvider did not produce a matcher for rule: {e
• service-name can't be empty

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/0a5544b15900dac7. Report an issue: GitHub.