skip to content

What is the Gradle Problems Report HTML, where is it written, and when does Gradle generate it?

level: juniorimportance: must knowfreq 45%

answer

  1. build/reports/problems/problems-report.html
  2. aggregates all reported problems + deprecations
  3. self-contained HTML
  4. clickable file:// link in console
  5. generated only when problems exist

basics

~10 s

It is an aggregated HTML file at build/reports/problems/problems-report.html that lists all problems and deprecations Gradle and plugins reported during the build. Gradle generates it automatically when problems exist.

solid answer

~40 s

The Problems Report is a single self-contained HTML file written to `build/reports/problems/problems-report.html` in the root project's build directory. It aggregates every problem reported through Gradle's Problems API during the build — deprecation warnings, configuration-cache issues, and any custom problems plugins emit — into one browsable page grouped by category. Gradle writes it automatically when at least one problem was reported, and prints a clickable `file://` link to it in the console near the end of the build. It exists so a noisy console full of warnings becomes a structured, navigable document: you open it in a browser, expand groups, and see each problem's details, location, and any documented solutions in one place rather than scrolling terminal output.

code

bash · 10 lines
bash
$ ./gradlew build
...
> Task :compileJava
[Incubating] Problems report is available at: file:///home/me/app/build/reports/problems/problems-report.html

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

# Open it:
$ open build/reports/problems/problems-report.html   # macOS
$ xdg-open build/reports/problems/problems-report.html # Linux

go deeper

for a junior

Know the path, that it aggregates problems/deprecations, and that a link prints in the console.

for a middle

Explain it is self-contained, generated only when problems exist, and that Gradle deprecations flow through the same Problems API into it.

for a senior

Tie it to the Problems API pipeline — reported Problems are aggregated and grouped by ProblemId for the report — and discuss its role in CI artifacts.

for a principal

Position it as the org-wide diagnostics surface: standardize uploading it as a CI artifact and using it to drive deprecation-burndown before major Gradle upgrades.

## What the Problems Report is Gradle's **Problems API** (stable since Gradle 8.6+, with the HTML report maturing through 8.x) gives plugins and Gradle internals a structured way to report issues — instead of just calling `logger.warn(...)`, code reports a *Problem* with an identity, severity, location, and solutions. All of those reported problems are then aggregated into a single **HTML report**. The report is written to: ``` <rootProject>/build/reports/problems/problems-report.html ``` It is a **self-contained** HTML file (styles and data inlined) so you can open it directly in a browser or attach it to a CI artifact without extra assets. ## When it is generated Gradle generates the report at the end of the build **whenever one or more problems were reported** during that build. Because Gradle's own deprecation warnings now flow through the Problems API, almost any build that emits a deprecation will produce the report. If no problems were reported, no report is written. ## How it surfaces in the console Near the end of the build, the console prints a line such as: ``` [Incubating] Problems report is available at: file:///path/to/build/reports/problems/problems-report.html ``` Many terminals render that `file://` URL as a clickable link. There is also a `--problems-report` view aspect: the link is what connects the terse console summary (e.g. "Deprecated Gradle features were used...") to the full structured detail. ## What it contains The page groups problems by their **ProblemId** hierarchy — a group label plus a specific id — so all problems of the same kind cluster together. For each problem you typically see: the human-readable label, severity (WARNING/ERROR/ADVICE), where it occurred (location), contextual details, and any solution text the reporter attached. This turns an unscannable wall of warnings into an expandable tree. ## Why it matters For a plugin author, the practical takeaway is: anything you report through the Problems API automatically shows up here, deduplicated and grouped, with no extra work. For a build engineer, it is the first place to look when a build prints "problems were reported" — open the HTML, not the raw log.

  • What happens to the report if a build reports zero problems?
    No report file is written and no link is printed — Gradle only generates the HTML when at least one problem was reported during that build.
  • Why is the file self-contained rather than referencing external CSS/JS?
    So it can be opened directly, emailed, or uploaded as a single CI artifact with no broken asset links or directory dependencies.

Think of the console as a stream of sticky notes flying past; the Problems Report is the corkboard where every note is pinned, sorted, and grouped so you can actually read them after the build.

  • Claiming the report is always generated even with no problems.
  • Saying it lives in each subproject's build dir rather than the root project's build/reports/problems/.

context