maxcellent
Using javadoc.io links in github ci builds makes builds unstable (related to CDN DDoS protection rules?)
See
- https://github.com/jdbi/jdbi/actions/runs/18354454844/job/52282708228
- https://github.com/jdbi/jdbi/actions/runs/18204929523/job/52193261014
and I have many more. They all fail at some point with
Error: Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.12.0:jar (basepom.default) on project jdbi3-sqlobject: MavenReportException: Error while generating Javadoc:
Error: Exit code: 1
Error: warning: URL https://junit.org/junit5/docs/5.13.3/api/element-list was redirected to https://docs.junit.org/5.13.3/api/element-list -- Update the command-line options to suppress this warning.
Error: [ERROR] error: Error fetching URL: https://javadoc.io/doc/org.testcontainers/jdbc/1.21.3/ (java.io.FileNotFoundException: https://javadoc.io/doc/org.testcontainers/jdbc/1.21.3/package-list)
Error: [ERROR] 1 error
Error: 1 warning
Error: Command line was: /usr/lib/jvm/temurin-21-jdk-amd64/bin/javadoc -J-Xmx1024m -J-Duser.language= -J-Duser.country= @options @argfile
The kicker: This reference is fetched for every module in the multi-module build. And yet, some of the modules succeed and them at some point (and not always the same point), the build fails because it can no longer fetch the file.
To me, this points to some CDN rule (cloudflare it seems) that kicks in if a specific IP fetches the same URL multiple times in a short(ish) period of time.
But that is what a CI build does. At this point, using javadoc.io as a reference for javadoc in my builds is making them unstable. Which is sad, because cross-linking between different javadoc sites is what makes javadoc powerful.
I don't know whether I am on the right track but this smells an awful lot like some DDos protection rule kicking in too eagerly. Any chance of changing this? My builds used to be rock-solid in the past.
hello, would you be able to share a project for me to build locally, so that I can test this issue?
I am seeing this as well e.g. https://github.com/release-engineering/pom-manipulation-ext/pull/1039
do
git clone [email protected]:jdbi/jdbi
cd jdbi
make docs
However, I noticed that the frequency of failure is very dependent where I run this. It seems that e.g. the github runners (on Azure) have a much higher failure rate than running this at home (which is home broadband). I am pretty sure that cloudflare uses some sort of IP address reputation for limits.
I played around with different options and it seems that using HTTP/1.1 might trigger this more easily. I got this out of curl:
❯ curl --http1.1 -v https://javadoc.io/doc/org.testcontainers/jdbc/1.21.3/element-list
* Host javadoc.io:443 was resolved.
* IPv6: 2606:4700:3038::6815:ea0b, 2606:4700:3038::6815:ea0a
* IPv4: 104.21.234.11, 104.21.234.10
* Trying [2606:4700:3038::6815:ea0b]:443...
* Connected to javadoc.io (2606:4700:3038::6815:ea0b) port 443
* ALPN: curl offers http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
* CAfile: /etc/ssl/cert.pem
* CApath: none
* (304) (IN), TLS handshake, Server hello (2):
* (304) (IN), TLS handshake, Unknown (8):
* (304) (IN), TLS handshake, Certificate (11):
* (304) (IN), TLS handshake, CERT verify (15):
* (304) (IN), TLS handshake, Finished (20):
* (304) (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256 / [blank] / UNDEF
* ALPN: server accepted http/1.1
* Server certificate:
* subject: CN=javadoc.io
* start date: Aug 18 08:55:52 2025 GMT
* expire date: Nov 16 09:52:30 2025 GMT
* subjectAltName: host "javadoc.io" matched cert's "javadoc.io"
* issuer: C=US; O=Google Trust Services; CN=WE1
* SSL certificate verify ok.
* using HTTP/1.x
> GET /doc/org.testcontainers/jdbc/1.21.3/element-list HTTP/1.1
> Host: javadoc.io
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 522 <none>
< Date: Thu, 09 Oct 2025 16:22:19 GMT
< Content-Type: text/plain; charset=UTF-8
< Content-Length: 15
< Connection: keep-alive
< Cache-Control: private, max-age=0, no-store, no-cache, must-revalidate, post-check=0, pre-check=0
< Expires: Thu, 01 Jan 1970 00:00:01 GMT
< Referrer-Policy: same-origin
< X-Frame-Options: SAMEORIGIN
< Server: cloudflare
< CF-RAY: 98bf36d84908ab7d-SJC
<
* Connection #0 to host javadoc.io left intact
error code: 522
Running the exact same command again returns the correct data.
(BTW the javadoc error is a red herring. javadoc tries both package-list and element-list and if it gets one, it will continue).
I recently encountered the same issue while attempting a release of weld-testing project via CI.
The CI runs kept failing while locally I was able to perform the build. The error was along these lines:
Error: [INFO] [ERROR] error: Error fetching URL: https://static.javadoc.io/jakarta.enterprise/jakarta.enterprise.cdi-api/4.0.1/ (java.io.FileNotFoundException: https://www.javadoc.io/doc/jakarta.enterprise/jakarta.enterprise.cdi-api/4.0.1/package-list)
I am able to reproduce this error now:
[ERROR] error: Error fetching URL: https://javadoc.io/doc/org.testcontainers/jdbc/1.21.3/ (java.io.FileNotFoundException: https://javadoc.io/doc/org.testcontainers/jdbc/1.21.3/package-list) [ERROR] 1 error
This is actually related to the issue raised by you: https://github.com/maxcellent/javadoc.io/issues/218
In this particular case, https://javadoc.io/doc/org.testcontainers/jdbc/1.21.3/package-list will return HTTP 404, while https://javadoc.io/doc/org.testcontainers/jdbc/1.21.3/element-list will return the real file.
I am not sure which mvn tool are you using. Can you advise what shall we return if package-list is not found? so that the script will continue trying element-list ?
I think what you see might be a red herring.
The weld-testing build mentioned in the comment before yours builds on Java 17,
so it will first request element-list and only if that is not found package-list.
I don't know whether it also tries package-list on errors beside 404.
But the point is, that it regularly fails to build the JavaDoc on GitHub Actions while it works fine locally.
As it builds fine locally that should mean it requests element-list as expected, so it might just be the error message referring to package-list if both were not found.
Got it. Now it looks like more related to https://github.com/maxcellent/javadoc.io/issues/198
In the mean time, are you able to try again? I have just increased number of threads serving the requests. Hopefully that will make things better?
Ultimately I can ask CF guys to relax the rule for GitHub IPs, specifically for element-list and package-list.
Unfortunately I am still seeing this ; for example this recent run https://github.com/project-ncl/pom-manipulation-ext/actions/runs/18656929977/job/53188229376?pr=1056
Yes, also just got the error after a push: https://github.com/spockframework/spock/actions/runs/18657330434/job/53189607894#step:5:813
Hi, we're getting the same error sometimes in our github ci. For example in this run: https://github.com/Kaktushose/jda-commands/actions/runs/19391153840/job/55486313408
I even got the problem now occasionally when running locally in a build that uses 4 javadoc.io links :-(
I even got the problem now occasionally when running locally in a build that uses 4 javadoc.io links :-(
+1 for me
I'm seeing the same error in CI:
- https://github.com/css4j/echosvg/actions/runs/20113062985/job/57715400825
- https://github.com/css4j/echosvg/actions/runs/20042899795/job/57481338537
As a work-around I switched now to -linkoffline.
That means for each version change I have to manually update the element-list / package-list stored in the project repository, but at least it now can generate links without needing to contact the server so cannot fail due to that.
Actually I had to change it because newer JavaDoc versions now fail when trying to link against Java 8 API as the Oracle server redirects to the Java 25 JavaDoc when requesting the non-existing Java 8 element-list. 🙄