pinpoint-apm/pinpoint · error · java.lang.IllegalStateException

already exist. annotationKey:${annotationKey}, exist:${exist

Error message

already exist. annotationKey:${annotationKey}, exist:${exist}

What it means

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.

Source

Thrown at commons-profiler/src/main/java/com/navercorp/pinpoint/common/profiler/trace/AnnotationKeyRegistry.java:62

        this.codeLookupTable = IntHashMapUtils.copy(buildMap);
        this.nameLookupTable = buildNameTable(buildMap.values());
        this.apiErrorLookupTable = buildApiMetaDataError(buildMap.values());
    }

    private Map<String, AnnotationKey> buildNameTable(Collection<AnnotationKey> buildMap) {
        final Map<String, AnnotationKey> nameLookupTable = new HashMap<>();
        for (AnnotationKey annotationKey : buildMap) {
            final AnnotationKey exist = nameLookupTable.put(annotationKey.getName(), annotationKey);
            if (exist != null) {
                throwDuplicatedAnnotationKey(annotationKey, exist);
            }
        }
        return nameLookupTable;
    }

    private static void throwDuplicatedAnnotationKey(AnnotationKey annotationKey, AnnotationKey exist) {
        throw new IllegalStateException("already exist. annotationKey:" + annotationKey + ", exist:" + exist);
    }

    private IntHashMap<AnnotationKey> buildApiMetaDataError(Collection<AnnotationKey> buildMap) {
        final IntHashMap<AnnotationKey> table = new IntHashMap<>();

        for (AnnotationKey annotationKey : buildMap) {
            if (annotationKey.isErrorApiMetadata()) {
                table.put(annotationKey.getCode(), annotationKey);
            }
        }
        return table;
    }

    @Override
    public AnnotationKey findAnnotationKey(int code) {
        final AnnotationKey annotationKey = codeLookupTable.get(code);
        if (annotationKey == null) {
            return AnnotationKey.UNKNOWN;

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Change the custom AnnotationKey to an unused code (prefer values outside built-in ranges, e.g. > 1000 in the user-defined range)
  2. Search registered/built-in AnnotationKey constants for the colliding code before assigning a new one
  3. If two plugins collide, coordinate/namespace the codes between them
  4. Check the 'exist' value in the message to identify exactly which key already owns the code

Example fix

// before
AnnotationKey key = AnnotationKeyFactory.of(30, "my.data"); // 30 is a built-in code
// after
AnnotationKey key = AnnotationKeyFactory.of(1900, "my.data"); // unique user-defined code
Defensive patterns

Strategy: validation

Validate before calling

AnnotationKey exist = registry.findAnnotationKey(annotationKey.getCode());
if (exist == null || exist.getCode() == annotationKey.getCode()) {
    throw new IllegalStateException("annotation key code " + annotationKey.getCode() + " already used");
}
// safe to register

Try / catch

try {
    registry.addAnnotationKey(key);
} catch (IllegalStateException e) {
    LOGGER.warn("duplicate annotation key code {}: {}", key.getCode(), e.getMessage());
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/01b8f8555fececa8. Report an issue: GitHub.