What causes "ProcessingEnvOptionsHolder not initialized yet." in pinpoint-apm/pinpoint?

Ensure the annotation processor's init(ProcessingEnvironment) method runs before any containsKey/getOption call.

pinpoint-apm/pinpoint · error · IllegalStateException

ProcessingEnvOptionsHolder not initialized yet.

Error message

ProcessingEnvOptionsHolder not initialized yet.

What it means

ProcessingEnvOptionsHolder caches the annotation-processor processing environment options for Pinpoint's MapStruct SPI. containsKey throws IllegalStateException when it is called before init(processingEnv) has populated the options map, i.e. the holder is queried outside the annotation-processing lifecycle.

Source

Thrown at commons-mapstruct-spi/src/main/java/com/navercorp/pinpoint/mapstruct/spi/ProcessingEnvOptionsHolder.java:64

    @Override
    public synchronized void init(ProcessingEnvironment processingEnv) {
        super.init(processingEnv);
        options = ImmutableMap.copyOf(processingEnv.getOptions());
    }

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        return false;
    }

    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latestSupported();
    }

    public boolean containsKey(String key) {
        if (options == null) {
            throw new IllegalStateException("ProcessingEnvOptionsHolder not initialized yet.");
        }
        return options.containsKey(key);
    }

    public String getOption(String key) {
        if (options == null) {
            throw new IllegalStateException("ProcessingEnvOptionsHolder not initialized yet.");
        }
        return options.get(key);
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

Ensure the annotation processor's init(ProcessingEnvironment) method runs before any containsKey/getOption call.
In tests, call the holder's init method with a mock ProcessingEnvironment (and its getOptions()) before asserting.
Check that no static field initializer touches the holder at class-load time before processing starts.

Example fix

// before
boolean has = ProcessingEnvOptionsHolder.getInstance().containsKey("mapstruct.defaultComponentModel");
// after (test setup)
ProcessingEnvOptionsHolder.getInstance().init(mockProcessingEnv);
boolean has = ProcessingEnvOptionsHolder.getInstance().containsKey("mapstruct.defaultComponentModel");

Defensive patterns

Strategy: validation

Validate before calling

if (!ProcessingEnvOptionsHolder.isInitialized()) {
    throw new IllegalStateException("Call init(processingEnv) before using ProcessingEnvOptionsHolder");
}
boolean has = ProcessingEnvOptionsHolder.getInstance().containsKey(key);

Try / catch

try {
    has = ProcessingEnvOptionsHolder.getInstance().containsKey(key);
} catch (IllegalStateException e) {
    // holder not initialized: initialize with env then retry
    ProcessingEnvOptionsHolder.getInstance().init(processingEnv);
    has = ProcessingEnvOptionsHolder.getInstance().containsKey(key);
}

Prevention

Only access the holder inside annotation processor lifecycle methods (init/process).
Avoid touching the holder from static initializers.
In tests, always call init() with a mock ProcessingEnvironment in setup.

When it happens

Trigger: Calling ProcessingEnvOptionsHolder.getInstance().containsKey(key) before the processor's init() has run — e.g. from code executed during class loading, a static initializer, or a unit test that never calls init().

Common situations: Unit-testing SPI code without simulating the annotation processor lifecycle; calling the holder from another processor or tool before the MapStruct processor initialized; refactorings that moved option lookups earlier in the lifecycle.

Related errors

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