Troubleshooting Maven Build for Jenkins: Common Errors and Solutions

Resolve Maven build failures in the Jenkins core project by configuring the compiler plugin correctly, purging conflicting dependencies, and applying the required JVM flags for Java 21+ compatibility.

The jenkinsci/jenkins repository is a multi-module Maven project that compiles the Jenkins automation server from source. When troubleshooting Maven build for Jenkins, developers frequently encounter compilation errors, dependency conflicts, and plugin configuration issues that require specific remediation steps defined in the parent pom.xml and CONTRIBUTING.md files. Understanding the project structure and common pitfalls ensures you can build the WAR artifact and run the development server successfully.

Jenkins Maven Project Structure

The Jenkins core is organized as a multi-module Maven project. The root pom.xml defines the parent POM, lists sub-modules (core, war, test, cli), and configures the repository at https://repo.jenkins-ci.org/public/ used by all modules.

The parent POM enforces code style, license compliance, and test execution through a set of standard plugins. Key configurations include the Maven compiler plugin settings in pom.xml (lines 44-52) and Surefire plugin timeouts defined for the test module.

Common Build Failures and Solutions

Compilation Failure: "package-info.java not found"

This error occurs when the compiler cannot generate package-info.class files. The Maven compiler plugin requires the -Xpkginfo:always flag, which is pre-configured in the parent POM at lines 44-52.

If you have overridden the plugin configuration in a local profile, restore the default settings to ensure the compiler generates the necessary package metadata during the build process.

ClassNotFoundException at Runtime

Maven occasionally resolves outdated snapshots or conflicting versions of transitive dependencies, causing runtime linkage errors. To resolve this, purge the corrupted artifacts from your local repository and rebuild with the latest parent version.

Run the following commands to clean and rebuild:

mvn dependency:purge-local-repository
mvn clean install -Dparent.version=2.576-SNAPSHOT

Test Hangs or Failures

The Surefire plugin configures a long timeout (forkedProcessTimeoutInSeconds = 3600) and disables symlink tests by default via the disable.symlink.tests property. If tests hang indefinitely, verify you have not explicitly set disable.symlink.tests to true in your environment, and ensure your system has sufficient resources to complete the full integration test suite.

Jetty ClassLoader Conflicts

Running the war module with the Maven Jetty plugin can clash with Jenkins’ internal classloader. This manifests as illegal-access errors or class loading exceptions when using Java 21+.

Use the recommended launch command from CONTRIBUTING.md (lines 45-52) that includes the required --add-opens JVM options:

MAVEN_OPTS='--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED' mvn -pl war jetty:run

License Validation Errors

The license-maven-plugin validates each artifact against the licenseCompleter.groovy script. Errors indicate missing or malformed LICENSE headers in source files.

Run the license check locally to identify offending files:

mvn license:check

Fix the reported files by adding the standard Jenkins license header, then rebuild.

Essential Maven Build Workflows

Quick WAR Build (Skip Tests)

For rapid feedback during UI development, build only the WAR artifact without running tests or lint checks:

mvn -am -pl war,bom -Pquick-build clean install

This command builds war/target/jenkins.war as documented in CONTRIBUTING.md (lines 31-35).

Full Build with Complete Validation

Execute the complete build pipeline including unit tests, functional tests, code-style checks, and license validation:

mvn clean install

This ensures your changes meet the project's quality gates before submission.

Code Formatting

Apply automatic backend code formatting to conform to project standards:

mvn spotless:apply

This fixes formatting issues in Java source files without manual intervention.

Frontend Asset Compilation

After building the WAR, compile JavaScript assets using Yarn. Ensure Node.js is available via the provided wrapper:

export PATH=$PWD/node:$PWD/node/node_modules/corepack/shims:$PATH
yarn

This step processes the frontend resources required for the Jenkins web interface.

Summary

• Compilation errors involving package-info.java require the -Xpkginfo:always compiler flag configured in the parent pom.xml.
• Dependency conflicts are resolved by purging the local Maven repository and rebuilding with the current parent version 2.576-SNAPSHOT.
• Java 21 compatibility demands specific --add-opens JVM options when running the development server via Jetty.
• License validation failures are checked with mvn license:check and fixed by updating file headers.
• Quick builds use the -Pquick-build profile to skip tests, while mvn spotless:apply ensures code formatting compliance.

Frequently Asked Questions

Why does my Jenkins Maven build fail with "package-info.java not found"?

The Maven compiler plugin requires the -Xpkginfo:always flag to generate package-info.class files automatically. This is configured in the parent pom.xml at lines 44-52. If you have customized plugin settings in your local environment, revert to the parent configuration to allow proper package metadata generation.

How do I resolve ClassNotFoundException errors when building Jenkins from source?

These exceptions typically indicate corrupted snapshots or version conflicts in your local Maven repository. Run mvn dependency:purge-local-repository to clear cached artifacts, then rebuild using the latest parent version specified in the root POM (currently 2.576-SNAPSHOT).

What are the correct JVM options for running the Jenkins development server on Java 21?

Java 21+ requires explicit --add-opens flags to allow reflective access that Jenkins' classloader utilizes. Set MAVEN_OPTS to include --add-opens java.base/java.lang=ALL-UNNAMED, --add-opens java.base/java.io=ALL-UNNAMED, and --add-opens java.base/java.util=ALL-UNNAMED before executing mvn -pl war jetty:run.

How can I speed up the Jenkins Maven build by skipping tests and checks?

Use the quick-build profile to compile only essential modules. Run mvn -am -pl war,bom -Pquick-build clean install to generate the WAR file without executing tests, license checks, or code style validations, reducing build time significantly during iterative development.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}