apache/skywalking · critical · IllegalArgumentException

hierarchy-definition.yml layer-levels: {lowerLayer} is not

Error message

hierarchy-definition.yml  layer-levels: {lowerLayer} is not defined.

What it means

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.

Source

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

    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(
                        "hierarchy-definition.yml hierarchy: " + layer + " layer-level should be greater than " + lowerLayer + " layer-level.");
                }
            }
        });
    }

    @Getter
    public static class MatchingRule {
        private final String name;
        private final String expression;
        private final BiFunction<Service, Service, Boolean> matcher;

        public MatchingRule(final String name, final String expression,
                            final BiFunction<Service, Service, Boolean> matcher) {

View on GitHub (pinned to 102af09b4a)

Solutions

1. 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.
2. Check for typos and exact case: layer names are matched as plain strings (this.layerLevels.get(lowerLayer) returns null on any mismatch).
3. If the layer should not participate in the hierarchy, remove its entry from the parent's 'hierarchy:' mapping instead of adding a level.
4. After editing, restart OAP and confirm the validation passes (no IllegalArgumentException in startup logs).

Example fix

# hierarchy-definition.yml — before
layer-levels:
  MCP_GATEWAY: 2
  GENERAL_ALS: 1
hierarchy:
  MCP_GATEWAY:
    NODE_JS: {}

# after (NODE_JS was missing a level)
layer-levels:
  MCP_GATEWAY: 2
  GENERAL_ALS: 1
  NODE_JS: 0
hierarchy:
  MCP_GATEWAY:
    NODE_JS: {}

// Validate hierarchy-definition.yml before boot
Map<String, Integer> levels = loadLayerLevels(yaml);
for (String layer : yaml.hierarchyKeys()) {
    Integer lvl = levels.get(layer);
    if (lvl == null) throw new ConfigException("layer-levels missing: " + layer);
    for (String lower : yaml.lowerLayersOf(layer)) {
        if (levels.get(lower) == null) {
            throw new ConfigException("layer-levels missing: " + lower);
        }
    }
}

Not applicable — thrown once at OAP startup; fix the YAML instead of catching.

When it happens

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

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

Related errors

• hierarchy-definition.yml {layer} is not a valid layer name.
• hierarchy-definition.yml layer-levels: {layer} is not defin
• 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/70d1ab6f394b526b. Report an issue: GitHub.