Javadoc "error: cannot find symbol" - Fix in CI

By Daniel Zoghalchali·Latchkey

The javadoc tool re-parses your sources to build docs and could not resolve a symbol - even though javac compiled it. Javadoc usually fails because it lacks the dependency classpath, the generated sources, or because newer javadoc treats reference errors as build failures.

What this error means

The javadoc goal fails with error: cannot find symbol (and often MavenReportException: Error while generating Javadoc: Exit code: 1). Compilation passed; only doc generation breaks.

maven

[ERROR] Failed to execute goal
org.apache.maven.plugins:maven-javadoc-plugin:3.7.0:jar (attach-javadocs)
on project app: ... error: cannot find symbol
  symbol:   class GeneratedMapper
  location: package com.example

Common causes

Javadoc missing the dependency classpath

A misconfigured run does not pass the same classpath as compilation, so types from dependencies are unresolved.

Generated sources not on the javadoc source path

Code produced by annotation processing (MapStruct, etc.) is not included, so references to it cannot be found.

Strict javadoc fails on doclint/reference errors

Newer JDK javadoc fails the build on reference or doclint problems that older versions only warned about.

How to fix it

Include generated sources for javadoc

Make sure generated-sources are produced and on the source path before javadoc runs.

Terminal

mvn -q generate-sources javadoc:jar
# generated code must exist when javadoc parses sources

Relax doclint while keeping reference checks honest

Disable doclint so missing-tag pedantry does not fail the build, then fix real reference errors.

pom.xml

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration><doclint>none</doclint></configuration>
</plugin>

Fix the unresolved reference

If a @link/@see points at a removed symbol, correct or remove it.

Java

/** See {@link com.example.NewType} */   // was a deleted class

How to prevent it

Run javadoc:jar in CI so doc errors surface with the build.
Ensure generated sources are produced before javadoc.
Keep @link/@see references valid; set doclint deliberately.

Frequently asked questions

What causes ""error: cannot find symbol" (javadoc)"?