apache/skywalking · critical · IllegalArgumentException

hierarchy-definition.yml hierarchy: {layer} layer-level shou

Error message

hierarchy-definition.yml hierarchy: {layer} layer-level should be greater than {lowerLayer} layer-level.

What it means

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.

Source

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

                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) {
            this.name = name;
            this.expression = expression;
            this.matcher = matcher;
        }

View on GitHub (pinned to 102af09b4a)

Solutions

1. 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.
2. Review the whole chain: if the child is itself a parent of deeper layers, every transitive level must remain strictly decreasing downward.
3. Restart OAP to re-run validation.

Example fix

# before
layer-levels:
  MCP_GATEWAY: 1
  NODE_JS: 2
hierarchy:
  MCP_GATEWAY:
    NODE_JS: {}

# after
layer-levels:
  MCP_GATEWAY: 2
  NODE_JS: 1
hierarchy:
  MCP_GATEWAY:
    NODE_JS: {}

// Before boot: enforce strict downward monotonicity
for (Map.Entry<String, Map<String, ?>> e : hierarchy.entrySet()) {
    int parent = levels.get(e.getKey());
    for (String lower : e.getValue().keySet()) {
        if (parent <= levels.get(lower)) {
            throw new ConfigException(e.getKey() + " level must be > " + lower + " level");
        }
    }
}

Not applicable — startup-time config failure; correct the YAML levels.

When it happens

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

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

Related errors

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