Maven is not working in Java 8 when Javadoc tags are incomplete

java maven migration java-8 javadoc

201,168

Solution 1

The best solution would be to fix the javadoc errors. If for some reason that is not possible (ie: auto generated source code) then you can disable this check.

DocLint is a new feature in Java 8, which is summarized as:

Provide a means to detect errors in Javadoc comments early in the development cycle and in a way that is easily linked back to the source code.

This is enabled by default, and will run a whole lot of checks before generating Javadocs. You need to turn this off for Java 8 as specified in this thread. You'll have to add this to your maven configuration:

<profiles>
  <profile>
    <id>java8-doclint-disabled</id>
    <activation>
      <jdk>[1.8,)</jdk>
    </activation>
    <properties>
      <javadoc.opts>-Xdoclint:none</javadoc.opts>
    </properties>
  </profile>
</profiles>
<build>
  <plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.9</version>
        <executions>
            <execution>
                <id>attach-javadocs</id>
                <goals>
                    <goal>jar</goal>
                </goals>
                <configuration>
                    <additionalparam>${javadoc.opts}</additionalparam>
                </configuration>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.3</version>
        <configuration>
          <reportPlugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <configuration>
                <additionalparam>${javadoc.opts}</additionalparam>
              </configuration>
            </plugin>
          </reportPlugins>
        </configuration>
      </plugin>
   </plugins>
</build>

For maven-javadoc-plugin 3.0.0+: Replace

<additionalparam>-Xdoclint:none</additionalparam>

with

<doclint>none</doclint>

Solution 2

The easiest approach to get things working with both java 8 and java 7 is to use a profile in the build:

<profiles>
  <profile>
    <id>doclint-java8-disable</id>
    <activation>
      <jdk>[1.8,)</jdk>
    </activation>

    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-javadoc-plugin</artifactId>
          <configuration>
            <additionalparam>-Xdoclint:none</additionalparam>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Solution 3

Here is the most concise way I am aware of to ignore doclint warnings regardless of java version used. There is no need to duplicate plugin configuration in multiple profiles with slight modifications.

<profiles>
  <profile>
    <id>doclint-java8-disable</id>
    <activation>
      <jdk>[1.8,)</jdk>
    </activation>
    <properties>
      <javadoc.opts>-Xdoclint:none</javadoc.opts>
    </properties>
  </profile>
</profiles>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.9.1</version>
      <executions>
        <execution>
          <id>attach-javadocs</id> <!-- The actual id should be apparent from maven output -->
          <configuration>
            <additionalparam>${javadoc.opts}</additionalparam>
          </configuration>
        </execution>
      </executions>
    </plugin>
    ...
  </plugins>
</build>

Tested on oracle/open jdk 6, 7, 8 and 11.

Solution 4

The shortest solution that will work with any Java version:

<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <additionalparam>-Xdoclint:none</additionalparam>
        </properties>
    </profile>
</profiles>

Just add that to your POM and you're good to go.

This is basically @ankon's answer plus @zapp's answer.

For maven-javadoc-plugin 3.0.0 users:

Replace

<additionalparam>-Xdoclint:none</additionalparam>

<doclint>none</doclint>

Solution 5

Add into the global properties section in the pom file:

<project>
    ...
    <properties>
        <additionalparam>-Xdoclint:none</additionalparam>
    </properties>

The common solution provided here in the other answers (adding that property in the plugins section) did not work for some reason. Only by setting it globally I could build the javadoc jar successfully.

View more solutions

201,168

Author by

Sergio

Updated on July 08, 2022

Comments

Sergio almost 2 years
Since I use Maven I have been able to build and install in my local repository projects that have incomplete Javadoc tags (for example, a missing parameter).

However, since I migrated to Java 8 (1.8.0-ea-b90) Maven is absolutely strict about missing documentation tags and show me lots of Javadoc errors related to Javadoc problems when I try to build or install a project where the Javadoc is not "perfect". Some of the projects I am trying to compile and install in my local repository are third party projects from which I do not have control. So the workaround of just fixing all the Javadocs in all these projects does not seem to be feasable in my scenario.

This is a small part of the output I see when I execute mvn clean package install in my project:
```
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9.026s
[INFO] Finished at: Mon Apr 08 21:06:17 CEST 2013
[INFO] Final Memory: 27M/437M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.9:jar (attach-javadocs) on project jpc: MavenReportException: Error while creating archive:
[ERROR] Exit code: 1 - /Users/sergioc/Documents/workspaces/heal/jpc/src/main/java/org/jpc/engine/prolog/PrologDatabase.java:10: error: @param name not found
[ERROR] * @param terms the terms to assert
[ERROR] ^
[ERROR] /Users/sergioc/Documents/workspaces/heal/jpc/src/main/java/org/jpc/engine/prolog/PrologDatabase.java:11: warning: no description for @return
[ERROR] * @return
[ERROR] ^
```
The Javadoc Maven plugin is configured like this in my POM:
```
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```
As I said before, everything is working fine if I go back to Java 7. Maybe is this a bug related to Maven running in Java 8? How could I make it work (i.e., being able to build the Javadoc of the project and install its code in my local repository) with Java 8? I have tested with both Maven 3.0.3 and 3.0.5 in OSX.

UPDATE:

If I change my Javadoc plugin configuration with <failOnError>false</failOnError> (thanks Martin):
```
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```
Then the project is installed in my local repository. However, the Javadoc JAR is still not generated.

A fragment of the output I see in the console with this new configuration is:

[ERROR] MavenReportException: Error while creating archive: Exit code: 1 - /Users/....java:18: warning: no @param ... Command line was: /Library/Java/Home/bin/javadoc @options @packages

Refer to the generated Javadoc files in '/Users/sergioc/Documents/workspaces/heal/minitoolbox/target/apidocs' dir.

at org.apache.maven.plugin.javadoc.AbstractJavadocMojo.executeJavadocCommandLine(AbstractJavadocMojo.java:5043) at org.apache.maven.plugin.javadoc.AbstractJavadocMojo.executeReport(AbstractJavadocMojo.java:1990) at org.apache.maven.plugin.javadoc.JavadocJar.execute(JavadocJar.java:181) at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:101) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:209) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145) at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:84) at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:59) at org.apache.maven.lifecycle.internal.LifecycleStarter.singleThreadedBuild(LifecycleStarter.java:183) at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:161) at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:320) at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:156) at org.apache.maven.cli.MavenCli.execute(MavenCli.java:537) at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:196) at org.apache.maven.cli.MavenCli.main(MavenCli.java:141) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:491) at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:290) at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:230) at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:409) at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:352)

Any workaround about how to build the sources, install the project and generate the Javadoc JAR in one step as it was working with Java 7?
Sergio almost 11 years

Thanks for the idea @Martin. With that property at least I can build and install the project again, however I am still missing the java doc jar (I need it to deploy to Maven central). I updated my question with the details of the experiment.
Feuermurmel about 10 years

Is there a way to make this work with JDK 8 as well as JDK 7? It fails on JDK 7 because its javadoc doesn't know this option.
Peter N. Steinmetz over 8 years

This is an important point as the lack of this setting in the site-plugin activation will cause release:perform to fail while release:prepare has worked fine. It can be a very annoying problem to find and fix.
Admin over 8 years

The best solution would probably be a Hybrid between your solution and the one Zapp provided bellow. If you leave it this way, the mvn site:site command will still be crashing. You should create a profile activated by the 1.8 jdk that sets a global property.
acvcu over 8 years

this is the only solution that worked for me. I read the answer here as well: blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.h‌tml
turbanoff over 8 years

BTW, Xdoclint parameter can be configured more flexible. E.g. to disable annoying HTML checks just use -Xdoclint:-html
user16655 over 8 years

This doesn't work for me unfortunately (Java 1.8, maven 3.0.5) Any ideas why?
Martin Höller over 8 years

Note, that the configuration of the maven-javadoc-plugin via the <reportPlugins> section of the maven-site-plugin is not recommended for recent versions of Maven 3.
pdem over 8 years

It is the best solution for me. It works for bots java 7 and java 8. But the way it work is a kind of magic :. How does this parameter "additionalParam" add to the plugin javadoc (and not to the others)
Fred Porciúncula over 8 years

@pdem The additional parameter is added to Maven, not to the Javadoc plugin. This solution works whether you're explicitly using the plugin or not.
Dave about 8 years

While this answers the question asked here, I'd like to advise future visitors to check peterh's answer first: stackoverflow.com/a/34809831/1180785 (most people hitting this issue will only have a handful of places to fix, so it's better to fix them than disable the check!)
Newtopian over 7 years

Completely agree here, that said, for generated code you can simply tell the plugin to not process code in a given package by adding a excludePackageNames section in the javadoc plugin`s configuration section. see maven.apache.org/plugins/maven-javadoc-plugin/examples/…
Wilfred Hughes almost 7 years

This is particularly useful because you can use it Jenkins too. Set 'Global MAVEN_OPTS' (under 'Configure System') to -Dadditionalparam=-Xdoclint:none and all your builds will work with Java 8.
Mehrad Sadegh over 6 years

This does not work with maven-javadoc-plugin version 3.0.0. I had to go back to version 3.0.0-M1 for making -Xdoclint:none work.
t7tran over 6 years

For maven-javadoc-plugin, use <doclint>none</doclint>. See maven.apache.org/plugins/maven-javadoc-plugin/…
fdelsert over 6 years

Also since maven-javadoc-plugin 3.0.0, <additionalparam/> is replaced by <additionalOptions/>. See issues.apache.org/jira/browse/MJAVADOC-475
Sergi over 6 years

Since maven-javadoc-plugin 3.0.0, you have to add<additionalJOption>-Xdoclint:none</additionalJOption> or <doclint>none</doclint> property to your <properties>
Garret Wilson almost 6 years

Can you clarify: with maven-javadoc-plugin 3.0.0 and above, if I simply specify <doclint>none</doclint> (with no JDK version-based activation), will it still fail on JDK less than 1.8, or does maven-javadoc-plugin automatically detect whether the doclint option is supported by the current version of Java?
Akom almost 6 years

This works for maven-javadoc-plugin 2.4 but starting in 2.5 (and all the way through 3.0.0), this causes an error: "Exit code: 1 - javadoc: error - invalid flag: -Xdoclint:none". So the solution is brittle.
Peter W almost 6 years

See doclint documentation here: maven.apache.org/plugins/maven-javadoc-plugin/…
PatS over 5 years

When using this with mvn release:perform the syntax needs to be mvn release:perform -Darguments="-Dmaven.javadoc.skip=true".
Thorsten Schöning over 5 years

maven.apache.org/plugins/maven-javadoc-plugin/…
Thorsten Schöning over 5 years

Sometimes -Xdoclint itself is not enough, but additional args are needed. Newer versions of the maven-javadoc-plugin provide additionalJOptions for that, older don't. A workaround is: <additionalJOption>"-Xdoclint:none" "--allow-script-in-comments"</additionalJOption> Quotes are important, else the plugin adds them and assumes only one arg instead of two, resulting in wrong args errors.
Thorsten Schöning over 5 years

The former works on Windows only, on Linux instead: javadoc: error - Illegal package name: ""-Xdoclint:none" "--allow-script-in-comments"" The outer quotes are added by the logging statement and not present on the shell. I guess the problem is that on Windows javadoc is executed by cmd.exe, which parses one large string as command line and splits the additionalJOptionas intended. On Linux the args are passed individually to the process directly and additionalJOption gets passed as one argument, leading to the error.
Thorsten Schöning over 5 years

According to Process Monitor, cmd.exe is not used. Java most likely simply builds one large command line and passes that to CreateProcess, so that it gets parsed by Windows as intended: Splitting args at spaces while honouring quotes.
clearlight about 5 years

By "configuration", what do you mean excatly? Really helps to be specific about steps to apply fixes. Please don't assume some noob or someone focused on a different layer knows much about some sub-invocation and how it's configured. To save time, could someone mention anything about how to quickly locate the maven configuration on macOS, Linux ...? On Debian Linux running dpkg -L maven implies /etc/maven/settings. And running: find . -name "*plugin*" in /usr/share/maven (also listed in dpkg -L output) shows. ./lib/maven-plugin-api-3.x.jar
clearlight about 5 years

That's SO much easier said than done since a lot of us running into these problems are trying to build unfamiliar opensource code that has a Maven dependency somewhere and we have no idea how it all works, so have no easy way to address the underlying causes. There's too much myopia about the context. People need to generalize the scope of the answers more and provide more specifics about how to make the fixes.
clearlight about 5 years

Resolved it for me building OpenGrok from github source in Feb'19. Should mention your patch goes into pom.xml in project's src/build directory. In my case all I had to do was search for maven-javadoc-plugin and then go to the <configuration></configuration> block already present and add <doclint>none</doclint>. As easy as all of this is once one knows, the context here is I'm trying to fix a different bug in OpenGrok and have never used Maven before and don't want to have to recurse into another sub project just to have to figure out how to apply quick fixes.
Oliver Gondža about 5 years

@clearlight, both build and profiles are top-level blocks in maven pom.xml. maven.apache.org/pom.html#Build.
Roman Khomyshynets about 5 years

mvn org.apache.maven.plugins:maven-javadoc-plugin:3.1.0:jar -DadditionalJOption=-Xdoclint:none - it worked for me
ZachSand almost 4 years

This was the most sufficient answer for me. I just wanted to test building during ongoing development when javadocs were still incomplete.
darkstar_mx over 3 years

Update: according to this issue: issues.apache.org/jira/browse/MNG-6871, it should work in Java version lower than JDK 8 update release 1.8.0_u121, otherwise it would complain you passed an unrecognized flag.