What does k6's `handleSummaryTimeout` option control, and how do you set it?

## What the clock covers k6 runs `handleSummary()` in a VU it creates specifically for the summary, with a context whose deadline is `handleSummaryTimeout`. Everything inside that boundary counts: - the synchronous body of your function; - anything you `await`, because the hook may be `async` and k6 unwraps the promise it returns; - timers and other event-loop work scheduled from the hook, which k6 drains before taking the result; - the init context of that fresh VU, which is executed again when the summary VU is created. The deadline is not a soft warning. When it passes, k6 interrupts the runtime and throws away whatever the call was going to produce, so the run ends with **no report at all** rather than a truncated one. ## How it is configured | knob | in the exported `options` object | environment variable | CLI flag | |---|---|---|---| | `handleSummaryTimeout` | yes | `K6_HANDLE_SUMMARY_TIMEOUT` | none | | summary mode | no | `K6_SUMMARY_MODE` | `--summary-mode` | That asymmetry is worth memorising, because the two settings that govern this hook are configured from opposite ends. The timeout is script-side and travels with the code; the summary mode is run-side and can be changed by whoever invokes k6. ```javascript export const options = { handleSummaryTimeout: '30s', }; export function handleSummary(data) { return { 'junit.xml': '<testsuites/>' }; } ``` ## What expiry looks like The error message is exact and easy to grep for: ``` handleSummary() execution timed out after 30 seconds ``` k6 attaches a hint alongside it — *you can increase the time limit via the handleSummaryTimeout option or the K6_HANDLE_SUMMARY_TIMEOUT environment variable* — and then logs `failed to handle the end-of-test summary`. As with every other failure in this path, the process's exit code is untouched, so a timed-out report does not turn a passing run red. ## Why a summary hook can be slow 1. **It talks to something.** The hook has the full k6 module surface available, so scripts sometimes upload the report over HTTP from inside it. A slow or hanging endpoint burns the budget directly. 2. **It renders something large.** Serialising and formatting a big summary object, especially into a verbose text format, is real CPU work in the script runtime. 3. **It awaits.** An `async` hook that never resolves consumes the entire allowance before k6 gives up. Lowering the value is as legitimate as raising it: a short budget on a report that should take milliseconds turns a hung upload into a fast, visible failure instead of two extra minutes at the end of every pipeline run. ## Choosing a value 1. **Measure what the hook actually costs.** A hook that formats the summary object and returns a string finishes in milliseconds; the two-minute allowance exists for the calls that do considerably more. 2. **Raise it when the hook does real work** — a large render, or a transfer to a service that is slow but dependable. k6 imposes no upper bound on the duration you set. 3. **Lower it when the hook should be instant.** A short budget converts a hung call into a fast, obvious failure instead of two extra minutes at the end of every run in the pipeline. 4. **Remember where the value lives.** It is a script option, so a value baked into a shared script becomes every run's behaviour; the environment variable is the per-invocation escape hatch. ## What the timeout does not do - It does not bound the test itself. By the time the hook is called, every iteration has already finished, so the budget only ever extends the closing seconds of a run. - It does not produce a partial artifact. The whole return value is lost, not truncated. - It does not fail the run. Like every other error in this path, a timed-out summary is logged and the process's exit status is left exactly as it was. ## Version notes In k6 v2 the value is a duration string such as `'30s'` or `'2m'`, the default is 120 seconds, and the option is one of the root keys of the exported `options` object rather than something you can pass on the command line. Because it is a script option, an archive or a shared script carries its own timeout with it wherever it runs.