How do you build a JMeter HTML dashboard from last night's results file without re-running the test?

## Report-only mode JMeter's dashboard generator is a separate stage from the load run. `-g <results file>` starts JMeter, skips the GUI and the engine entirely, feeds that file to the generator and writes the output folder: ``` jmeter -g /var/perf/2026-09-08/results.jtl -o /var/perf/2026-09-08/dashboard ``` The long form is `--reportonly`, which is a good description of what it does. No test plan is loaded, no threads start, nothing is sent to the system under test. The only inputs are the results file, the report generator properties, and the destination folder. ## The combination JMeter refuses `-g` is declared incompatible with four other options: - `-n` (`--nongui`) — report-only mode is not a test run, so the non-GUI switch is meaningless; - `-l` (`--logfile`) — the results file is already supplied as `-g`'s argument; - `-r` and `-R` — there is nothing to distribute to remote engines. Passing any of them alongside `-g` fails in the argument parser: JMeter prints an incompatible-options error, dumps the usage block and returns without doing any work. Since `-n` is muscle memory for anyone who runs JMeter from a shell, `jmeter -n -g results.jtl -o report` is the classic first attempt, and it produces no report and no test — only a wall of usage text that is easy to scroll past in CI output. ## What a regenerate can and cannot change The generator merges `bin/reportgenerator.properties` with the JMeter properties in force at generation time, and the JMeter properties win. So a second pass over the same file can change anything the report layer computes or displays: 1. the APDEX thresholds, `jmeter.reportgenerator.apdex_satisfied_threshold` and `apdex_tolerated_threshold`, which re-score every sample in the file; 2. `jmeter.reportgenerator.overall_granularity`, the bucket width of the over-time graphs; 3. `jmeter.reportgenerator.exporter.html.series_filter` and its companions, which decide what is displayed; 4. cosmetic settings such as `jmeter.reportgenerator.report_title`. What it cannot change is anything that was never written to the file. The report is only as rich as the columns the run saved, and no flag can recover a measurement that was not recorded. If the file is missing or unreadable, the generator refuses immediately with `Cannot read test results file : <path>` instead of producing an empty dashboard. ## Practical shape of the workflow A useful habit is to treat the results file as the durable artefact and the dashboard as disposable: - keep the JTL from each run under a dated path; - generate the dashboard beside it, into a folder that does not exist yet; - when the report needs to look different, change the property and rebuild rather than rerunning the load. The `-o` rules are exactly the same as for an end-of-run report: the folder must not exist or must be empty, and `-f` will clear it for you. Note that in report-only mode `-f` clears only the output folder — the file named by `-g` is the input and is never deleted. ## Cost and placement Generation is real work: the whole file is streamed and aggregated, and the generator uses a scratch directory (`jmeter.reportgenerator.temp_dir`, `temp` by default, relative to JMeter's working directory) when it needs disk. Running it separately from the load means that cost lands on whatever machine you choose rather than on the injector at the end of a run, and a failed report no longer arrives attached to a finished test whose numbers you still want. ## The same job from the GUI The menu item `Tools` -> `Generate HTML report` does what `-g` does, from a dialog with three fields: the results file (csv or jtl), the `user.properties` file to apply, and an output directory. The dialog enforces the same emptiness rule, and the output directory is in practice required: a blank field arrives as an empty string rather than as "unset", so it resolves to JMeter's working directory and errors there instead of falling back to `<JMETER_HOME>/bin/report-output` — a default the manual still promises but only a null the dialog never sends can reach. Because it takes the properties file explicitly, it is a convenient way to try a different report configuration against a file without editing the installed properties. Generation that runs long enough to look hung is governed by `generate_report_ui.generation_timeout`, which the shipped `jmeter.properties` documents at `300000` milliseconds.