docs(troubleshooting): add Maven Central 429 rate-limit section

Author: DmitriyLewen

docs/guide/references/troubleshooting.md

@@ -120,6 +120,26 @@ $ GITHUB_TOKEN=XXXXXXXXXX trivy image --vex repo [YOUR_IMAGE]
     `GITHUB_TOKEN` doesn't help with the rate limit for the vulnerability database and other assets.
     See https://github.com/aquasecurity/trivy/discussions/8009
 
+### Maven Central rate limiting (HTTP 429)
+
+When scanning Java projects, Trivy resolves transitive dependencies by downloading POM files from Maven Central (or any other configured remote Maven repository) when they are missing from the local `~/.m2` cache. Sonatype tightened the [Maven Central rate limits](https://central.sonatype.org/faq/429-error/) in May 2026; scans of large projects with an empty local cache routinely hit the per-IP block.
+
+!!! error
+    ```
+    FATAL Error remote Maven repository returned 429 Too Many Requests for https://repo.maven.apache.org/maven2/.../<artifact>-<version>.pom. Retry-After: 1800.
+    The repository blocks all subsequent requests from this IP until the block clears.
+    To avoid this, populate the local Maven cache before scanning (e.g. run `mvn dependency:resolve` and cache ~/.m2 in CI).
+    ```
+
+The block is per-IP and applies to *all* subsequent requests from the affected IP — including artifacts that would normally be served from the Cloudflare edge cache. The `Retry-After` value can be tens of minutes on the first violation and grows on repeat, so Trivy fails fast on the first `429` instead of retrying.
+
+Recommended mitigations:
+
+- **Populate `~/.m2` before scanning.** Run `mvn dependency:resolve` against the project so that every POM/JAR is cached locally. Trivy will then use the local cache and never contact the remote repository.
+- **Cache `~/.m2` between CI runs.** Use your CI's cache action keyed on `pom.xml` checksums so that subsequent runs reuse already-downloaded artifacts.
+- **Wait for the block to expire.** The `Retry-After` value in the error tells you the minimum wait. Repeated scans during the block will extend it.
+- **Use `--offline-scan`** if you only want to scan what is already in the local cache and avoid any remote lookups.
+
 ### Unable to open JAR files
 
 !!! error