apache/skywalking · critical · UnexpectedException

LAL rule {ruleName} layerDefinitions entry rejected: {def}

Error message

LAL rule {ruleName} layerDefinitions entry rejected: {def}

What it means

Thrown when an inline layerDefinitions: entry in a LAL rule fails Layer.register() — the central registry that enforces reserved ordinal ranges, name uniqueness, ordinal uniqueness and sealed-state for Layer definitions. The rule name and the offending LayerDefinition toString are embedded. It is an UnexpectedException, so it fails the module/provider boot that loaded the rule.

Source

Thrown at oap-server/analyzer/log-analyzer/src/main/java/org/apache/skywalking/oap/log/analyzer/v2/provider/LALConfigs.java:214

        }
    }

    /**
     * Funnel any inline {@code layerDefinitions:} entries through {@code Layer.register}.
     * Conflict checks (reserved-range, name uniqueness, ordinal uniqueness, sealed-state) live
     * in {@code Layer.register}; failures here surface with the offending rule name in
     * the stack trace.
     */
    private static void registerInlineLayers(final String ruleName, final LALConfigs configs) {
        final List<LayerDefinition> defs = configs.getLayerDefinitions();
        if (defs == null || defs.isEmpty()) {
            return;
        }
        for (final LayerDefinition def : defs) {
            try {
                def.register();
            } catch (RuntimeException e) {
                throw new UnexpectedException(
                    "LAL rule " + ruleName + " layerDefinitions entry rejected: " + def, e);
            }
        }
    }
}

View on GitHub (pinned to 102af09b4a)

Solutions

1. Check the Layer.register cause in the stack trace — it names the exact violation (reserved range, duplicate name, duplicate ordinal, sealed)
2. Give each custom layer a unique name and a unique ordinal outside reserved ranges
3. Remove the layerDefinitions entry if the layer is already registered by a plugin or another rule
4. Keep all definitions of one layer in a single rule file to avoid ordering-dependent duplicates

Example fix

# before (two rules both declare)
layerDefinitions:
  - name: MY_LAYER
    ordinal: 3

# after (declare once, unique ordinal outside reserved range)
layerDefinitions:
  - name: MY_LAYER
    ordinal: 9001

// Before loading rules with inline layers, pre-validate uniqueness/ranges:
// Set<String> names = new HashSet<>(); Set<Integer> ordinals = new HashSet<>();
// for (LayerDefinition d : defs) {
//     if (!names.add(d.name()) || !ordinals.add(d.ordinal())) throw new IllegalStateException("duplicate layer def");
// }

try {
    def.register();
} catch (RuntimeException e) {
    // rule name is embedded; fix the layerDefinitions entry (name/ordinal conflict)
    // and restart — there is no runtime recovery, registration is boot-time
}

When it happens

Trigger: A layerDefinitions entry whose name or ordinal collides with an already-registered Layer (built-in or from an earlier rule); an ordinal inside a reserved range owned by the project; registering onto a sealed Layer registry state.

Common situations: Two custom rules defining the same layer name with different ordinals; picking an ordinal inside the range reserved for SkyWalking built-in layers; re-declaring a layer that a satellite/receiver plugin already registered via SPI.

Related errors

• Failed to load LAL config rules
• Layer {} has already set {} rule.
• tag() reads LogData tags but the input type is {inputTypeNam
• Failed to compile LAL expression: {dsl}
• Failed to load MAL rules

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