apache/skywalking · critical · IllegalArgumentException

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

Error message

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

What it means

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.

Source

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

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

    @Getter

View on GitHub (pinned to 102af09b4a)

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

Example fix

# before
layer-levels:
  MESH: 2
hierarchy:
  MESH:
    MESH_CP: gateway-rule   # MESH_CP level missing
# after
layer-levels:
  MESH: 2
  MESH_CP: 1
hierarchy:
  MESH:
    MESH_CP: gateway-rule

Defensive patterns

Strategy: validation

Validate before calling

Set<String> leveled = layerLevels.keySet();
Set<String> referenced = new HashSet<>();
hierarchyDefinition.forEach((l, lowers) -> { referenced.add(l); referenced.addAll(lowers.keySet()); });
assert referenced.stream().allMatch(leveled::contains) : "layers missing from layer-levels: " + disjoint(referenced, leveled);

Try / catch

Fail fast at startup; a hierarchy without levels cannot be order-validated, so catching would produce an inconsistent service topology view.

Prevention

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

When it happens

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

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

Related errors

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