Re: [DISCUSS] Automatic JDK toolchain selection when running JDK is incompatible (4.1.0)

Thanks everyone for the feedback. I've updated the PR to follow the
approach Gerd outlined (and Maarten/Matthias endorsed):


*1. Core = diagnose, don't repair.*
When the running JDK cannot honor the requested source/release level, Maven
now emits one clear, actionable error instead of letting javac fail
cryptically:

[ERROR] Project requires --source 6 which needs JDK <= 11, but the running
JDK 21 no longer supports it.
[ERROR] To fix: run 'mvnup' to add the maven-toolchains-plugin with
automatic JDK discovery,
[ERROR] or install JDK 11 and configure it in toolchains.xml or via the
maven-toolchains-plugin.

No auto-discovery, no silent repair — the build fails and tells you exactly
what to do.

*2. Discovery + selection stays in maven-toolchains-plugin.*

The filesystem discovery code has been removed from core. We rely entirely
on the plugin's select-jdk-toolchain goal for JDK discovery and selection.


*3. mvnup bridges the gap.*
A new ToolchainPluginStrategy in mvnup detects old source levels and adds
the maven-toolchains-plugin with the select-jdk-toolchain goal and a
version constraint (e.g. <version>(,8]</version> for source 5). This is a
one-time POM upgrade — explicit, version-controlled, no magic at build time.

The PR is ready for review, CI is green across all platforms
(Linux/macOS/Windows × JDK 17/21/25).

PR: https://github.com/apache/maven/pull/12633

Cheers,
Guillaume

Le lun. 3 août 2026 à 14:18, Guillaume Nodet <[email protected]> a écrit :

> Hi all,
>
> I've opened a draft PR for a quality-of-life feature in Maven 4.1.0:
> automatic JDK toolchain selection when the running JDK cannot compile the
> project's declared source/release level.
>
> PR: https://github.com/apache/maven/pull/12633
>
> The problem
>
> When a project declares <maven.compiler.source>6</maven.compiler.source>
> (or uses <release>, <targetVersion>, or compiler plugin
> <configuration><source>), and you run Maven with JDK 21 — which dropped
> --source 6 support — the build fails with a cryptic javac error. The user
> has to figure out they need to install a compatible JDK and either
> configure toolchains.xml or add the maven-toolchains-plugin to their build.
> This is a frequent stumbling block, especially when maintaining older
> projects.
>
> The solution
>
> Maven now automatically detects the incompatibility and searches for a
> compatible JDK — first in configured toolchains (toolchains.xml), then by
> lazily discovering JDK installations on the filesystem. If a compatible JDK
> is found, it's selected as the compilation toolchain and a warning is
> emitted:
>
> [WARNING] Project requires --source 6 which is not supported by JDK 21.
> [WARNING] Automatically selected JDK 11 (discovered at
> /usr/lib/jvm/java-11) for compilation.
>
>
> This is a zero-cost feature: the auto-selection logic only runs when the
> running JDK genuinely cannot handle the project's source level. Normal
> builds are completely unaffected.
>
> Design decisions worth discussing
>
> 1. Filesystem discovery — The discoverer scans well-known locations
> (SDKMAN, IntelliJ .jdks/, Gradle, jEnv, JBang, asdf, mise, OS-specific
> paths like /usr/lib/jvm). Version is read from the JDK release file — no
> java processes are spawned. This is essentially what
> maven-toolchains-plugin's ToolchainDiscoverer does, but moved into core and
> made lazy. Does this make the plugin's auto-discovery redundant? Should we
> deprecate it?
>
> 2. Source level detection — We read the source level from multiple places
> in priority order: Model 4.1.0 <source><targetVersion>, then
> maven.compiler.release/maven.compiler.source properties, then compiler
> plugin <configuration><release>/<source>. Is this the right precedence? Are
> there other places we should check?
>
> 3. "Newest compatible" strategy — When multiple compatible JDKs are found,
> we pick the newest one (highest major version that still supports the
> required source level). The rationale is that a newer JDK gives better
> performance and diagnostics. Should this be configurable?
>
> 4. Compat layer — The v3 ToolchainManagerFactory bridge now passes the
> discoverer through, so plugins using the v3 API also benefit. This felt
> important for the transition period.
>
> CI is green on all platforms (Linux/macOS/Windows × JDK 17/21/25).
>
> Feedback and reviews welcome.
>
> Guillaume
>
>

-- 
------------------------
Guillaume Nodet