{"record":{"id":"01b8f8555fececa8","repo":"pinpoint-apm/pinpoint","slug":"already-exist-annotationkey-annotationkey-exi","errorCode":null,"errorMessage":"already exist. annotationKey:${annotationKey}, exist:${exist}","messagePattern":"already exist\\. annotationKey:(.+?), exist:(.+?)","errorType":"exception","errorClass":"java.lang.IllegalStateException","httpStatus":null,"severity":"error","filePath":"commons-profiler/src/main/java/com/navercorp/pinpoint/common/profiler/trace/AnnotationKeyRegistry.java","lineNumber":62,"sourceCode":"\n        this.codeLookupTable = IntHashMapUtils.copy(buildMap);\n        this.nameLookupTable = buildNameTable(buildMap.values());\n        this.apiErrorLookupTable = buildApiMetaDataError(buildMap.values());\n    }\n\n    private Map<String, AnnotationKey> buildNameTable(Collection<AnnotationKey> buildMap) {\n        final Map<String, AnnotationKey> nameLookupTable = new HashMap<>();\n        for (AnnotationKey annotationKey : buildMap) {\n            final AnnotationKey exist = nameLookupTable.put(annotationKey.getName(), annotationKey);\n            if (exist != null) {\n                throwDuplicatedAnnotationKey(annotationKey, exist);\n            }\n        }\n        return nameLookupTable;\n    }\n\n    private static void throwDuplicatedAnnotationKey(AnnotationKey annotationKey, AnnotationKey exist) {\n        throw new IllegalStateException(\"already exist. annotationKey:\" + annotationKey + \", exist:\" + exist);\n    }\n\n    private IntHashMap<AnnotationKey> buildApiMetaDataError(Collection<AnnotationKey> buildMap) {\n        final IntHashMap<AnnotationKey> table = new IntHashMap<>();\n\n        for (AnnotationKey annotationKey : buildMap) {\n            if (annotationKey.isErrorApiMetadata()) {\n                table.put(annotationKey.getCode(), annotationKey);\n            }\n        }\n        return table;\n    }\n\n    @Override\n    public AnnotationKey findAnnotationKey(int code) {\n        final AnnotationKey annotationKey = codeLookupTable.get(code);\n        if (annotationKey == null) {\n            return AnnotationKey.UNKNOWN;","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/commons-profiler/src/main/java/com/navercorp/pinpoint/common/profiler/trace/AnnotationKeyRegistry.java#L44-L80","documentation":"AnnotationKeyRegistry.buildNameTable assembles the lookup table from all registered AnnotationKeys. When two distinct AnnotationKey objects share the same code, throwDuplicatedAnnotationKey aborts registry construction with an IllegalStateException, because the code-to-key mapping would otherwise be ambiguous. This is an internal invariant: annotation key codes must be globally unique.","triggerScenarios":"Registering a custom AnnotationKey whose code collides with an existing one (built-in or another plugin's), typically via AnnotationKeyFactory or by adding duplicate entries to the builder collection that buildNameTable consumes.","commonSituations":"Custom plugin code copies a built-in annotation key constant (e.g. 9000-range codes) and registers it again; two plugins define the same custom code; a Pinpoint upgrade introduces a built-in key with a code a user already claimed.","solutions":["Change the custom AnnotationKey to an unused code (prefer values outside built-in ranges, e.g. > 1000 in the user-defined range)","Search registered/built-in AnnotationKey constants for the colliding code before assigning a new one","If two plugins collide, coordinate/namespace the codes between them","Check the 'exist' value in the message to identify exactly which key already owns the code"],"exampleFix":"// before\nAnnotationKey key = AnnotationKeyFactory.of(30, \"my.data\"); // 30 is a built-in code\n// after\nAnnotationKey key = AnnotationKeyFactory.of(1900, \"my.data\"); // unique user-defined code","handlingStrategy":"validation","validationCode":"AnnotationKey exist = registry.findAnnotationKey(annotationKey.getCode());\nif (exist == null || exist.getCode() == annotationKey.getCode()) {\n    throw new IllegalStateException(\"annotation key code \" + annotationKey.getCode() + \" already used\");\n}\n// safe to register","typeGuard":null,"tryCatchPattern":"try {\n    registry.addAnnotationKey(key);\n} catch (IllegalStateException e) {\n    LOGGER.warn(\"duplicate annotation key code {}: {}\", key.getCode(), e.getMessage());\n}","preventionTips":["Assign custom annotation key codes well outside built-in ranges","Grep built-in AnnotationKey constants before choosing a code","Keep a shared registry of assigned codes across team plugins"],"tags":["duplicate-key","registry","annotation"],"backgroundTag":"internal-invariant-violation","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}