apache/skywalking · critical · UnexpectedException

hierarchy-definition.yml not found.

Error message

hierarchy-definition.yml not found.

What it means

HierarchyDefinitionService.init() reads hierarchy-definition.yml (rule text plus DslYamlLineIndex source lines). Any IOException while locating or reading the file is wrapped in this UnexpectedException. Despite the message saying 'not found', it covers all read failures — missing file, unreadable path, or closed stream.

Source

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

            this.matchingRules = ruleExpressions.entrySet().stream().map(entry -> {
                final BiFunction<Service, Service, Boolean> matcher = builtRules.get(entry.getKey());
                if (matcher == null) {
                    throw new IllegalStateException(
                        "HierarchyRuleProvider did not produce a matcher for rule: " + entry.getKey());
                }
                final MatchingRule matchingRule = new MatchingRule(entry.getKey(), entry.getValue(), matcher);
                return Map.entry(entry.getKey(), matchingRule);
            }).collect(toMap(Map.Entry::getKey, Map.Entry::getValue));
            hierarchy.forEach((layer, lowerLayers) -> {
                final Map<String, MatchingRule> rules = new HashMap<>();
                lowerLayers.forEach((lowerLayer, ruleName) -> {
                    rules.put(lowerLayer, this.matchingRules.get(ruleName));
                });
                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()) {

View on GitHub (pinned to 102af09b4a)

Solutions

1. Verify the hierarchy-definition.yml path exists and is readable by the OAP user (check the exception's wrapped cause for the exact path)
2. Restore the file from the official distribution or your config management if it was deleted
3. In custom images, ensure COPY of the full config directory, not just application.yml

Example fix

# Dockerfile — before
COPY config/application.yml /skywalking/oap-libs/../config/
# after — copy the whole config dir including hierarchy-definition.yml
COPY config/ /skywalking/config/

Path p = Path.of(configPath, "hierarchy-definition.yml");
if (!Files.isReadable(p)) {
    throw new IllegalStateException("Missing/unreadable hierarchy config: " + p.toAbsolutePath());
}

Catch the UnexpectedException only at deployment tooling level to print the wrapped IOException cause (exact missing path); the OAP itself should keep failing fast.

When it happens

Trigger: The hierarchy-definition.yml configured path does not exist in the OAP distribution; the file exists but the OAP process lacks read permission; the config directory was altered in a custom Docker image.

Common situations: Custom Docker images or Helm charts that copy only application.yml and drop other resource files; setting a custom hierarchy definition path that was never created; filesystem permission issues in containerized deployments.

Related errors

• HierarchyRuleProvider did not produce a matcher for rule: {e
• 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
• hierarchy-definition.yml hierarchy: {layer} layer-level shou

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