{"record":{"id":"5963e8eef5154906","repo":"apache/skywalking","slug":"component-name-name-in-component-server-mappin","errorCode":null,"errorMessage":"Component name [{name}] in Component-Server-Mappings doesn't exist in component define. ","messagePattern":"Component name \\[(.+?)\\] in Component-Server-Mappings doesn't exist in component define\\. ","errorType":"exception","errorClass":"InitialComponentCatalogException","httpStatus":null,"severity":"critical","filePath":"oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/ComponentLibraryCatalogService.java","lineNumber":108,"sourceCode":"                if (COMPONENT_SERVER_MAPPING_SECTION.equals(componentName)) {\n                    settings.forEach((name, serverName) -> {\n                        nameMapping.put((String) name, (String) serverName);\n                    });\n                } else {\n                    Integer componentId = (Integer) settings.get(\"id\");\n                    componentName2Id.put((String) componentName, componentId);\n                    componentId2Name.put(componentId, (String) componentName);\n                    Integer priority = (Integer) settings.get(\"priority\");\n                    if (priority == null) {\n                        priority = 50;\n                    }\n                    componentIDPriorities.put(componentId, priority);\n                }\n            });\n\n            nameMapping.forEach((name, serverName) -> {\n                if (!componentName2Id.containsKey(name)) {\n                    throw new InitialComponentCatalogException(\n                        \"Component name [\" + name + \"] in Component-Server-Mappings doesn't exist in component define. \");\n                }\n                if (!componentName2Id.containsKey(serverName)) {\n                    throw new InitialComponentCatalogException(\n                        \"Server componentId name [\" + serverName + \"] in Component-Server-Mappings doesn't exist in component define. \");\n                }\n\n                componentId2ServerId.put(componentName2Id.get(name), componentName2Id.get(serverName));\n            });\n            nameMapping.clear();\n        } catch (FileNotFoundException e) {\n            log.error(\"component-libraries.yml not found.\", e);\n        }\n\n    }\n\n    /**\n     * @return true if the given componentB has high priority","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/ComponentLibraryCatalogService.java#L90-L126","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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","If the component is genuinely new, first define it (name + id + priority) in the components section, then reference it in the mapping","Validate the YAML structure (mapping entries are name -> serverName pairs at the right indent) after editing"],"exampleFix":"# before\nComponent-Server-Mappings:\n  Tomcat9: Tomcat   # 'Tomcat9' is not defined anywhere\n# after\nComponent-Server-Mappings:\n  Tomcat: Tomcat","handlingStrategy":"validation","validationCode":"# YAML pre-flight: every mapping key must be a defined component\nimport yaml\ncfg = yaml.safe_load(open('component-libraries.yml'))\ndefined = set()\nfor section in cfg.values():\n    if isinstance(section, dict):\n        defined.update(str(k) for k in section.keys())\nfor name in cfg.get('Component-Server-Mappings', {}):\n    assert name in defined, f'undefined component in mapping: {name}'","typeGuard":null,"tryCatchPattern":"Do not catch — InitialComponentCatalogException must abort startup so the broken catalog is fixed, not silently skipped.","preventionTips":["Run the YAML cross-check script in CI whenever component-libraries.yml is customized","After merging upstream catalog changes, diff your mapping keys against the current definitions","Keep custom components in a clearly separated block with their own ID range"],"tags":["configuration","yaml","component-catalog","startup","custom-config"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}