# Troubleshooting Maven Build for Jenkins: Common Errors and Solutions

> Troubleshoot Maven build errors in Jenkins. Learn to fix common issues like compiler plugin problems, dependency conflicts, and JVM flag compatibility for Java 21+.

- Repository: [Jenkins/jenkins](https://github.com/jenkinsci/jenkins)
- Tags: tutorial
- Published: 2026-07-30

---

**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`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml) and [`CONTRIBUTING.md`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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:

```bash
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`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md) (lines 45-52) that includes the required `--add-opens` JVM options:

```bash
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:

```bash
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:

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

```

This command builds `war/target/jenkins.war` as documented in [`CONTRIBUTING.md`](https://github.com/jenkinsci/jenkins/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/jenkinsci/jenkins/blob/main/package-info.java) require the `-Xpkginfo:always` compiler flag configured in the parent [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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.