apache/skywalking · error · IllegalStateException

Failed to compile hierarchy rule: {name}, expression: {expre

Error message

Failed to compile hierarchy rule: {name}, expression: {expression}

What it means

Thrown by Layer.registerDynamic when the name is already registered with a different ordinal and/or isNormal flag. Registration is idempotent only when both value and isNormal match the existing entry; any mismatch is a conflict because layer ordinals are persisted in storage and a silent redefinition would corrupt historical data.

Source

Thrown at oap-server/analyzer/hierarchy/src/main/java/org/apache/skywalking/oap/server/core/config/v2/compiler/CompiledHierarchyRuleProvider.java:76

    }

    @Override
    public Map<String, BiFunction<Service, Service, Boolean>> buildRules(
            final Map<String, String> ruleExpressions,
            final Map<String, Integer> ruleLines) {
        final Map<String, BiFunction<Service, Service, Boolean>> rules = new HashMap<>();
        ruleExpressions.forEach((name, expression) -> {
            try {
                // Per rule, not per file: the generator labels the class _L<line>_ and puts
                // (file:line) in SourceFile, so a single file-level coordinate would give every
                // hierarchy rule the same line.
                final Integer line = ruleLines.get(name);
                generator.setSourceRef(DslSourceRef.ofRule(
                    HIERARCHY_RULE_FILE, line == null ? 0 : line));
                rules.put(name, generator.compile(name, expression));
                log.debug("Compiled hierarchy rule: {}", name);
            } catch (Exception e) {
                throw new IllegalStateException(
                    "Failed to compile hierarchy rule: " + name
                        + ", expression: " + expression, e);
            }
        });
        return rules;
    }
}

View on GitHub (pinned to 102af09b4a)

Solutions

1. Align the new definition with the existing one: use the same ordinal and isNormal value already registered (the error message prints them)
2. If the change is intentional, restart the OAP with a clean definition rather than hot-reloading, and be aware ordinals already persisted in storage are frozen
3. Rename the new layer if it is genuinely a different layer

Example fix

// before — MY_LAYER already registered as ordinal=100001, normal=true
Layer.registerDynamic("MY_LAYER", 100500, true);
// after
Layer.registerDynamic("MY_LAYER", 100001, true); // idempotent, returns existing

Layer existing = Layer.nameOf(name);
boolean idempotent = existing == Layer.UNDEFINED
    || (existing.value() == value && existing.isNormal() == isNormal);

When it happens

Trigger: Calling Layer.registerDynamic("MY_LAYER", 100500, true) when MY_LAYER already exists with ordinal 100001 (or with isNormal=false). Happens when a runtime hot-update rule redefines a layer with changed attributes, or when two rule files claim the same name with different ordinals.

Common situations: Editing the ordinal in a layerDefinitions block and hot-reloading without restarting the OAP; two independent MAL/LAL runtime rules defining the same layer name differently; changing the isNormal flag of an existing layer.

Related errors

• Hierarchy rule parsing failed: {errors} in expression: {expr
• Load meter analyzer configs failed
• Failed to load GenAI configuration file.
• Output type {outputTypeName} has no setter for field '{field
• Output field '{fieldName}' requires outputType to be set in

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