{"record":{"id":"acbeae04561189f9","repo":"apache/skywalking","slug":"server-componentid-name-servername-in-componen","errorCode":null,"errorMessage":"Server componentId name [{serverName}] in Component-Server-Mappings doesn't exist in component define. ","messagePattern":"Server componentId 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":112,"sourceCode":"                } 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\n     */\n    public boolean compare(int componentA, int componentB) {\n        final Integer priorityA = componentIDPriorities.getOrDefault(componentA, 50);\n        final Integer priorityB = componentIDPriorities.getOrDefault(componentB, 50);","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/ComponentLibraryCatalogService.java#L94-L130","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the exception message for the exact serverName, then define that name in the component catalog section or fix the reference","Keep mappings symmetric: both key and value must exist as component definitions before adding the mapping","Run a YAML lint and a quick name cross-check after customizing the catalog"],"exampleFix":"# before\nComponent-Server-Mappings:\n  Netty: Netty4Server   # typo: undefined server component\n# after\nComponent-Server-Mappings:\n  Netty: Netty4","handlingStrategy":"validation","validationCode":"for name, server_name in cfg.get('Component-Server-Mappings', {}).items():\n    assert name in defined, f'undefined client component: {name}'\n    assert server_name in defined, f'undefined server component: {server_name}'","typeGuard":null,"tryCatchPattern":"Let startup fail; no runtime catch — a partial component map would silently corrupt server-side component attribution.","preventionTips":["Validate BOTH sides of every mapping entry in a config-lint step","When renaming a component, grep the mappings section for stale references","Prefer copy-editing the shipped catalog rather than rewriting it"],"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"}