{"record":{"id":"3de152f461de1cba","repo":"pinpoint-apm/pinpoint","slug":"unable-to-set-registry-for-annotationkeyprovider","errorCode":null,"errorMessage":"Unable to set registry for AnnotationKeyProvider","messagePattern":"Unable to set registry for AnnotationKeyProvider","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"commons-profiler/src/main/java/com/navercorp/pinpoint/common/profiler/trace/TraceMetadataRegistrar.java","lineNumber":60,"sourceCode":"    }\n\n    private TraceMetadataRegistrar() {\n        throw new AssertionError();\n    }\n\n    public static void registerServiceTypes(ServiceTypeLocator serviceTypeLocator) {\n        try {\n            serviceTypeLocatorField.set(null, serviceTypeLocator);\n        } catch (IllegalAccessException e) {\n            throw new IllegalStateException(\"Unable to set registry for ServiceTypeProvider\", e);\n        }\n    }\n\n    public static void registerAnnotationKeys(AnnotationKeyLocator annotationKeyLocator) {\n        try {\n            annotationKeyLocatorField.set(null, annotationKeyLocator);\n        } catch (IllegalAccessException e) {\n            throw new IllegalStateException(\"Unable to set registry for AnnotationKeyProvider\", e);\n        }\n    }\n}","sourceCodeStart":42,"sourceCodeEnd":63,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/commons-profiler/src/main/java/com/navercorp/pinpoint/common/profiler/trace/TraceMetadataRegistrar.java#L42-L63","documentation":"TraceMetadataRegistrar.registerAnnotationKeys reflectively injects an AnnotationKeyLocator into a static field of AnnotationKeyProvider. An IllegalAccessException is wrapped in this IllegalStateException, meaning annotation keys cannot be registered and any later AnnotationKey lookup will fail. Same bootstrap-reflection failure family as the ServiceTypeProvider variant.","triggerScenarios":"Calling TraceMetadataRegistrar.registerAnnotationKeys(...) when the pre-cached annotationKeyLocatorField cannot be set: caller lacks reflective access to AnnotationKeyProvider's package (JDK strong encapsulation), field is final in a changed version, or the class was loaded by a foreign classloader.","commonSituations":"JDK 9+ running without --add-opens for the pinpoint package; mismatched pinpoint jar versions where AnnotationKeyProvider's field layout differs; agent/app-server classloader isolation preventing access to the declaring class.","solutions":["Align commons-profiler jar versions so TraceMetadataRegistrar and AnnotationKeyProvider match.","Add --add-opens JVM flags (or downgrade/upgrade JDK) so reflection into the pinpoint package is permitted.","Confirm the bootstrap sequence: the class holding the field must be initialized via the intended registrar path once, before AnnotationKeyProvider methods are used."],"exampleFix":"// before\nTraceMetadataRegistrar.registerAnnotationKeys(locator); // throws under JDK 17 strong encapsulation\n// after\n// JVM args: --add-opens com.navercorp.pinpoint.common.profiler.trace=ALL-UNNAMED\nTraceMetadataRegistrar.registerAnnotationKeys(locator);","handlingStrategy":"try-catch","validationCode":"boolean ok;\ntry {\n    Class<?> c = Class.forName(\"com.navercorp.pinpoint.common.profiler.trace.AnnotationKeyProvider\");\n    Field f = c.getDeclaredField(\"annotationKeyLocator\");\n    f.setAccessible(true);\n    ok = java.lang.reflect.Modifier.isStatic(f.getModifiers());\n} catch (ReflectiveOperationException e) { ok = false; }\nif (!ok) throw new IllegalStateException(\"AnnotationKeyProvider field not reflectively settable; check --add-opens/jar versions\");","typeGuard":null,"tryCatchPattern":"try {\n    TraceMetadataRegistrar.registerAnnotationKeys(locator);\n} catch (IllegalStateException e) {\n    logger.error(\"Failed to register annotation keys\", e);\n    throw e;\n}","preventionTips":["Match commons-profiler jar versions across the deployment.","Grant reflective access on JDK 9+ with --add-opens for the pinpoint trace package.","Initialize AnnotationKeyProvider via the registrar before any AnnotationKey query.","Avoid mixing pinpoint classes loaded from different classloaders."],"tags":["java","reflection","bootstrap","classloader"],"backgroundTag":"module-init-failed","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"}