pinpoint-apm/pinpoint · error · IllegalStateException

Unable to set registry for ServiceTypeProvider

Error message

Unable to set registry for ServiceTypeProvider

What it means

TraceMetadataRegistrar.registerServiceTypes uses reflection to set a static field inside ServiceTypeProvider (a class initialized before pinpoint's real classpath is built). If the reflective Field.set fails with IllegalAccessException, this IllegalStateException wraps it, meaning the bootstrap reflection setup is broken and service types cannot be resolved.

Source

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

    private static Field getRegistryField(Class<?> providerClazz, String fieldName) {
        try {
            Field registryField = providerClazz.getDeclaredField(fieldName);
            registryField.setAccessible(true);
            return registryField;
        } catch (NoSuchFieldException e) {
            throw new AssertionError("Expected field '" + fieldName + "' not found in " + providerClazz.getName());
        }
    }

    private TraceMetadataRegistrar() {
        throw new AssertionError();
    }

    public static void registerServiceTypes(ServiceTypeLocator serviceTypeLocator) {
        try {
            serviceTypeLocatorField.set(null, serviceTypeLocator);
        } catch (IllegalAccessException e) {
            throw new IllegalStateException("Unable to set registry for ServiceTypeProvider", e);
        }
    }

    public static void registerAnnotationKeys(AnnotationKeyLocator annotationKeyLocator) {
        try {
            annotationKeyLocatorField.set(null, annotationKeyLocator);
        } catch (IllegalAccessException e) {
            throw new IllegalStateException("Unable to set registry for AnnotationKeyProvider", e);
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Ensure TraceMetadataRegistrar and ServiceTypeProvider come from the same pinpoint commons-profiler version (align jar versions on the classpath).
2. On JDK 9+, add JVM flags to open the package, e.g. --add-opens <module>/<package>=ALL-UNNAMED, or run on the same module setup the library expects.
3. Check that the class initializing ServiceTypeProvider went through the intended bootstrap path (TraceMetadataRegistrar.registerServiceTypes called exactly once from the correct classloader) before any ServiceType lookup.

Example fix

// before (JDK 9+, IllegalAccessException)
java -jar app.jar
// after
java --add-opens java.base/java.lang=ALL-UNNAMED -cp pinpoint-commons-profiler.jar -jar app.jar

// verify same-version jars and reflective access before registering
boolean ok;
try {
    Class<?> c = Class.forName("com.navercorp.pinpoint.common.profiler.trace.ServiceTypeProvider");
    Field f = c.getDeclaredField("serviceTypeLocator");
    f.setAccessible(true);
    ok = java.lang.reflect.Modifier.isStatic(f.getModifiers());
} catch (ReflectiveOperationException e) { ok = false; }
if (!ok) throw new IllegalStateException("Pinpoint bootstrap reflection unavailable; check versions/JDK flags");

try {
    TraceMetadataRegistrar.registerServiceTypes(locator);
} catch (IllegalStateException e) {
    logger.error("Pinpoint metadata bootstrap failed", e);
    throw e; // cannot continue without service types
}

When it happens

Trigger: Calling TraceMetadataRegistrar.registerServiceTypes(...) when the static serviceTypeLocatorField was obtained from a ServiceTypeProvider class that is no longer accessible/settable (field not static, class loaded by an incompatible classloader, or field made final/removed in a different Pinpoint version).

Common situations: Bootstrapping pinpoint commons-profiler on JDK 9+ with strong encapsulation blocking reflective access to the class's package; mixing pinpoint versions where TraceMetadataRegistrar and ServiceTypeProvider come from different jars; custom classloader isolation (e.g. in an agent or app server) so the field's declaring class is not accessible to the caller.

Related errors

• Unable to set registry for AnnotationKeyProvider
• initialize fail Caused by:
• invoke fail Caused by:
• bootstrapClassLoader not found Caused by:
• boot method invoke failed. Error:

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