You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Propagate the mojo execution scope to threads started by a plugin, or document that it is not supported? #13827
Should Maven offer plugins a way to run work on another thread inside the current mojo execution scope, or is the expectation that plugins never let scoped components be created off the Mojo thread?
Case
maven-site-plugin's site:run serves pages from the JDK HTTP server's own threads, after execute() has started the server. A Doxia parser contributed by a site dependency, the Asciidoctor one, injects MavenProject. Parsers are looked up per document, so it is instantiated on a server thread and fails with
OutOfScopeException: Cannot access Key[type=MavenProject, annotation=[none]] outside of a scoping block
at MojoExecutionScopeModule.configure(MojoExecutionScopeModule.java:47)
MojoExecutionScope keeps its state in a ThreadLocal (3.9.x org.apache.maven.execution.scope.internal, 4.x org.apache.maven.impl.di). SessionScope does not; it uses a CopyOnWriteArrayList, so session-scoped components work from any thread. Plugins see only org.apache.maven.execution.scope (the annotations and WeakMojoExecutionListener), so they cannot enter or seed the mojo execution scope themselves.
What the plugin does now
apache/maven-site-plugin#1350 keeps the server's thread pool for requests and hands only document rendering to the Mojo thread, which loops over a queue until the server stops. It works with every Maven version, but it serializes rendering and any plugin starting a server or a worker pool has to rediscover it.
Options
Context propagation API. In the exported org.apache.maven.execution.scope package (and the Maven 4 API equivalent), something that captures the current mojo execution scope on the Mojo thread and returns a wrapper (Runnable/Callable/Executor) that enters the captured state on whichever thread runs the task and exits it afterwards.
Guidance only. Document that mojo-execution-scoped objects are only available on the Mojo thread, and that components meant to be created by plugins on other threads must not inject them; the producer of the component (here Doxia Sitetools) should pass what is needed explicitly. That is being discussed for this case in Give Doxia parsers the document and site context instead of Maven injection maven-doxia-sitetools#736.
Something else that already exists and I missed.
The site plugin needs option 2 or its current workaround anyway while it supports Maven 3.9. The question is whether option 1 is worth adding for 3.10 or 4.x, or whether option 2 is the intended model.
The root cause here is that MojoExecutionScope has always been ThreadLocal-based (since MNG-5530 in 2012), and that is intentional: when running with -T N, multiple mojo executions run concurrently on different threads, and the ThreadLocal isolates their scoped state.
Maven 3.9.x
Option 2 (documentation + guidance) is the right answer for 3.x. The workaround in apache/maven-site-plugin#1350 — routing document rendering back to the mojo thread via a queue — is the correct pattern. Plugins that spawn worker threads must not let those threads look up @MojoExecutionScoped components, because there is no scope state on those threads. This should be documented clearly.
Maven 4
The situation is cleaner by design:
A v4 plugin gets a fresh Injector per mojo execution (created in DefaultMavenPluginManager), with Session, Project, MojoExecution, and Log bound directly as plain instances via bindInstance. There is no ThreadLocal involved at all. A mojo simply declares:
...and gets the right instances for that execution automatically. If the mojo spawns worker threads, it passes those objects explicitly as parameters — no scope, no magic.
v4 mojos are thread-safe by design: each execution gets a fresh mojo instance with its own injector, so no mojo state is ever shared between concurrent executions. This is what makes v4 mojos safe to run in parallel builds without locking.
If a plugin needs to share state across multiple mojo invocations (e.g. an initialize mojo and a verify mojo sharing computed data), it can inject a @SessionScoped or @Singleton bean — those are resolved from the shared container, not the per-execution local injector, so they survive across executions for the duration of the build. Those shared beans are the only place where explicit thread-safety is required.
A core extension (.mvn/extensions.xml) lives in the shared container and can use @SessionScoped for session-lifetime components. The existing @MojoExecutionScoped (v3 annotation, Plexus/Sisu/Guice path) still works for extensions that need per-execution lifecycle — but even then, the ThreadLocal constraint applies: the scope is only valid on the mojo thread.
On org.apache.maven.api.di.MojoExecutionScoped (the v4 annotation)
This annotation exists in maven-api-di but is unfinished and unusable: the Guice binding in MojoExecutionScopeModule is commented out, there is no proxy path for injecting it into a wider scope (unlike @SessionScoped which creates a JDK proxy transparently), and no production code in Maven itself uses it. We should remove it from the v4 API to avoid confusion — v4 plugins do not need it (they get execution context via direct injection), and extensions that need scoped components should use the established v3 annotation or @SessionScoped.
On Option 1 (context propagation API)
Not justified. It would work around a design problem rather than fixing it. Plugins that need concurrent work should pass context explicitly, not rely on transparent scope propagation across threads.
Long-term for site:run
Migrating maven-site-plugin to the v4 API is the right fix. Doxia parsers would receive Session and Project via direct injection or explicit parameter passing — no scoped lookups, no ThreadLocal, no thread issues.
Activity
gnodet commentedon Nov 4, 2026
The root cause here is that
MojoExecutionScopehas always beenThreadLocal-based (since MNG-5530 in 2012), and that is intentional: when running with-T N, multiple mojo executions run concurrently on different threads, and theThreadLocalisolates their scoped state.Maven 3.9.x
Option 2 (documentation + guidance) is the right answer for 3.x. The workaround in apache/maven-site-plugin#1350 — routing document rendering back to the mojo thread via a queue — is the correct pattern. Plugins that spawn worker threads must not let those threads look up
@MojoExecutionScopedcomponents, because there is no scope state on those threads. This should be documented clearly.Maven 4
The situation is cleaner by design:
A v4 plugin gets a fresh
Injectorper mojo execution (created inDefaultMavenPluginManager), withSession,Project,MojoExecution, andLogbound directly as plain instances viabindInstance. There is noThreadLocalinvolved at all. A mojo simply declares:...and gets the right instances for that execution automatically. If the mojo spawns worker threads, it passes those objects explicitly as parameters — no scope, no magic.
v4 mojos are thread-safe by design: each execution gets a fresh mojo instance with its own injector, so no mojo state is ever shared between concurrent executions. This is what makes v4 mojos safe to run in parallel builds without locking.
If a plugin needs to share state across multiple mojo invocations (e.g. an
initializemojo and averifymojo sharing computed data), it can inject a@SessionScopedor@Singletonbean — those are resolved from the shared container, not the per-execution local injector, so they survive across executions for the duration of the build. Those shared beans are the only place where explicit thread-safety is required.A core extension (
.mvn/extensions.xml) lives in the shared container and can use@SessionScopedfor session-lifetime components. The existing@MojoExecutionScoped(v3 annotation, Plexus/Sisu/Guice path) still works for extensions that need per-execution lifecycle — but even then, theThreadLocalconstraint applies: the scope is only valid on the mojo thread.On
org.apache.maven.api.di.MojoExecutionScoped(the v4 annotation)This annotation exists in
maven-api-dibut is unfinished and unusable: the Guice binding inMojoExecutionScopeModuleis commented out, there is no proxy path for injecting it into a wider scope (unlike@SessionScopedwhich creates a JDK proxy transparently), and no production code in Maven itself uses it. We should remove it from the v4 API to avoid confusion — v4 plugins do not need it (they get execution context via direct injection), and extensions that need scoped components should use the established v3 annotation or@SessionScoped.On Option 1 (context propagation API)
Not justified. It would work around a design problem rather than fixing it. Plugins that need concurrent work should pass context explicitly, not rely on transparent scope propagation across threads.
Long-term for
site:runMigrating
maven-site-pluginto the v4 API is the right fix. Doxia parsers would receiveSessionandProjectvia direct injection or explicit parameter passing — no scoped lookups, noThreadLocal, no thread issues.