apache/skywalking · critical · InitialComponentCatalogException

Component name [{name}] in Component-Server-Mappings doesn't

Error message

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

What it means

ComponentLibraryCatalogService loads component-libraries.yml, which defines components (with IDs and priorities) plus a Component-Server-Mappings section mapping client components to their server-side counterpart. When iterating that mapping, a client-side component NAME that does not appear in the component definitions throws this InitialComponentCatalogException at OAP startup.

Source

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

                if (COMPONENT_SERVER_MAPPING_SECTION.equals(componentName)) {
                    settings.forEach((name, serverName) -> {
                        nameMapping.put((String) name, (String) serverName);
                    });
                } 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

View on GitHub (pinned to 102af09b4a)

Solutions

1. Open component-libraries.yml and verify the exact spelling/case of the key inside Component-Server-Mappings matches a name defined in the component catalog
2. If the component is genuinely new, first define it (name + id + priority) in the components section, then reference it in the mapping
3. Validate the YAML structure (mapping entries are name -> serverName pairs at the right indent) after editing

Example fix

# before
Component-Server-Mappings:
  Tomcat9: Tomcat   # 'Tomcat9' is not defined anywhere
# after
Component-Server-Mappings:
  Tomcat: Tomcat

# YAML pre-flight: every mapping key must be a defined component
import yaml
cfg = yaml.safe_load(open('component-libraries.yml'))
defined = set()
for section in cfg.values():
    if isinstance(section, dict):
        defined.update(str(k) for k in section.keys())
for name in cfg.get('Component-Server-Mappings', {}):
    assert name in defined, f'undefined component in mapping: {name}'

Do not catch — InitialComponentCatalogException must abort startup so the broken catalog is fixed, not silently skipped.

When it happens

Trigger: Editing component-libraries.yml and adding a Component-Server-Mappings entry whose key references a component name that is misspelled or not defined under the component sections (e.g. mapping 'Tomcat9' while only 'Tomcat' is defined).

Common situations: Customizing component names/IDs for a proxy or framework not in the stock catalog; merging upstream component-libraries.yml changes and dropping a definition while keeping its mapping; YAML indentation moving an entry out of the components block.

Related errors

• Server componentId name [{serverName}] in Component-Server-M
• 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/5963e8eef5154906. Report an issue: GitHub.