Build: any reactor build stopping before 'package' fails with "module not found: com.clickhouse.data" in clickhouse-client java11 module-info

Start by reproducing the failure with mvn -B -pl clickhouse-client -am -DskipTests test, then inspect the java11 compiler execution in pom.xml and the affected module-info.java files. Check the documented commands in AGENTS.md and CONTRIBUTING.md; done means test-phase reactor builds succeed while verify/install builds and the multi-release jar contents remain unchanged.

Description

Since the JPMS service-loader change (PR #2941, issue #2669) added clickhouse-client/src/main/java11/module-info.java, any Maven reactor build that stops at a lifecycle phase earlier than package fails while compiling that module descriptor:

error: module not found: com.clickhouse.data

This includes the two build commands the repo itself documents for module development:

• AGENTS.md:35 — "Run a module with dependencies: mvn -pl <module> -am test"
• CONTRIBUTING.md:133 — mvn -pl <module> -am test

and also the plain full-reactor mvn test. A contributor on a clean checkout therefore hits a hard build failure with the documented command.

Builds that reach package or later (package, install, verify) succeed.

Steps to reproduce

1. Clean checkout of main (reproduced at 05393dd6, the #2941 merge), JDK 17 + Maven 3.9.15.
2. mvn -B -pl clickhouse-client -am -DskipTests test → FAILS
   (same for mvn -B -pl client-v2 -am -DskipTests test, and for full-reactor mvn -B -DskipTests test)
3. mvn -B clean then mvn -B -pl clickhouse-client -am -DskipTests package → SUCCEEDS

Error Log or Exception StackTrace

[INFO] --- compiler:3.14.0:compile (java11) @ clickhouse-client ---
[INFO] Toolchain in maven-compiler-plugin: JDK[/opt/java/openjdk]
[INFO] Compiling 1 source file with javac [forked debug release 11 module-path] to target/classes/META-INF/versions/11
[ERROR] COMPILATION ERROR :
/work/clickhouse-client/src/main/java11/module-info.java:[10,38] error: module not found: com.clickhouse.data
[INFO] 1 error
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.14.0:compile (java11) on project clickhouse-client: Compilation failure

Reactor summary:

[INFO] clickhouse-java .................................... SUCCESS
[INFO] ClickHouse Data Processing Utilities ............... SUCCESS
[INFO] ClickHouse Java Client ............................. FAILURE
[INFO] ClickHouse Client API .............................. SKIPPED

Expected Behaviour

mvn -pl <module> -am test (and mvn test) build successfully, as documented in AGENTS.md and CONTRIBUTING.md.

Root cause

The java11 execution of maven-compiler-plugin in the parent pom.xml (executions block around lines 558-575, bound to the compile phase by the compile-java11 profile at lines 766-788) compiles with multiReleaseOutput=true, so the descriptor of each module is written to target/classes/META-INF/versions/11/module-info.class and not to target/classes/module-info.class.

When the upstream module is built in the same reactor run but that run never reaches package, Maven puts the directory clickhouse-data/target/classes on the path instead of a jar. javac applies multi-release semantics only to jars, so for a directory root it sees no module-info.class, treats clickhouse-data/target/classes as an unnamed/automatic entry, and requires transitive com.clickhouse.data in clickhouse-client/src/main/java11/module-info.java:10 cannot be resolved.

Confirmations:

• find clickhouse-data/target/classes -name module-info.class → clickhouse-data/target/classes/META-INF/versions/11/module-info.class only.
• mvn -Dj8 -pl clickhouse-client -am -DskipTests test succeeds — -Dj8 deactivates the compile-java11 profile, so the failing execution never runs.
• package succeeds because clickhouse-data is jarred before clickhouse-client compiles, and the jar carries Multi-Release: true.

CI does not catch this, because the CI jobs run verify/install-level builds, which are past package.

Six modules have such a descriptor and are affected the same way once they depend on each other: clickhouse-data, clickhouse-client, clickhouse-http-client, clickhouse-jdbc, jdbc-v2, clickhouse-r2dbc.

Suggested fix

Options, in rough order of preference:

1. Make the java11 execution resolve upstream module descriptors independently of the reactor phase — e.g. add an explicit --module-path / --patch-module for the reactor dependencies, or configure the execution with useModulePath=false and pass -Xlint-safe compiler args, so the descriptor compiles against the classpath instead of the module path. (module-info.java compilation does need the required modules to be resolvable, so simply disabling the module path may need --add-reads/--patch-module care.)
2. Also emit a root module-info.class (or run the java11 execution at prepare-package with a jarred upstream), so target/classes is a valid module root during a test-phase reactor build.
3. If neither is acceptable, update AGENTS.md and CONTRIBUTING.md so the documented commands are the ones that work (mvn -pl <module> -am verify -DskipITs=true, or install of the upstream modules first), and note the limitation.

Contrast case that must keep working: mvn install / mvn verify full and subset builds, and the multi-release jar contents (META-INF/versions/11/module-info.class present in the published jars) must not change.

Configuration

Environment

• Cloud
• Client version: 0.10.0-rc1-SNAPSHOT (main @ 05393dd6)
• Language version: OpenJDK 17.0.18 (with JDK 8 toolchain also available), Maven 3.9.15
• OS: Ubuntu 24.04 (container)

ClickHouse Server

• Not relevant — this is a build/packaging failure; no server interaction is reached.

---

Found by automated analysis of this client while working on an unrelated change, and verified by building pristine main in a clean container (not by inspection only). Regression from #2941 / #2669.