apache/skywalking · critical · InitialComponentCatalogException

Server componentId name [{serverName}] in Component-Server-M

Error message

Server componentId name [{serverName}] in Component-Server-Mappings doesn't exist in component define. 

What it means

The second validation pass over Component-Server-Mappings in component-libraries.yml: the VALUE of each mapping (the server-side component the client maps to) must itself be a defined component name. If the server-side name is unknown, this InitialComponentCatalogException is thrown at startup naming the offending serverName.

Source

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

                } else {
                    Integer componentId = (Integer) settings.get("id");
                    componentName2Id.put((String) componentName, componentId);
                    componentId2Name.put(componentId, (String) componentName);
                    Integer priority = (Integer) settings.get("priority");
                    if (priority == null) {
                        priority = 50;
                    }
                    componentIDPriorities.put(componentId, priority);
                }
            });

            nameMapping.forEach((name, serverName) -> {
                if (!componentName2Id.containsKey(name)) {
                    throw new InitialComponentCatalogException(
                        "Component name [" + name + "] in Component-Server-Mappings doesn't exist in component define. ");
                }
                if (!componentName2Id.containsKey(serverName)) {
                    throw new InitialComponentCatalogException(
                        "Server componentId name [" + serverName + "] in Component-Server-Mappings doesn't exist in component define. ");
                }

                componentId2ServerId.put(componentName2Id.get(name), componentName2Id.get(serverName));
            });
            nameMapping.clear();
        } catch (FileNotFoundException e) {
            log.error("component-libraries.yml not found.", e);
        }

    }

    /**
     * @return true if the given componentB has high priority
     */
    public boolean compare(int componentA, int componentB) {
        final Integer priorityA = componentIDPriorities.getOrDefault(componentA, 50);
        final Integer priorityB = componentIDPriorities.getOrDefault(componentB, 50);

View on GitHub (pinned to 102af09b4a)

Solutions

1. Check the exception message for the exact serverName, then define that name in the component catalog section or fix the reference
2. Keep mappings symmetric: both key and value must exist as component definitions before adding the mapping
3. Run a YAML lint and a quick name cross-check after customizing the catalog

Example fix

# before
Component-Server-Mappings:
  Netty: Netty4Server   # typo: undefined server component
# after
Component-Server-Mappings:
  Netty: Netty4

for name, server_name in cfg.get('Component-Server-Mappings', {}).items():
    assert name in defined, f'undefined client component: {name}'
    assert server_name in defined, f'undefined server component: {server_name}'

Let startup fail; no runtime catch — a partial component map would silently corrupt server-side component attribution.

When it happens

Trigger: A mapping like 'Netty: Netty4-Server' where 'Netty4-Server' was never defined in the component catalog; renaming a server component without updating mappings that point to it.

Common situations: Custom component-libraries.yml edits that rename or remove a server-side component but leave stale references; merging upstream catalog changes where a server component name changed.

Related errors

• Component name [{name}] in Component-Server-Mappings doesn't
• 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

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