GoogleChrome/lighthouse · error · Error

Need at least one step before getting the result

Error message

Need at least one step before getting the result

What it means

Thrown by auditGatherSteps() when the gather steps array is empty. This function is called by createFlowResult() and generateReport() to audit collected steps and produce the final flow result. At least one completed step (navigation, timespan, or snapshot) must exist before requesting results — an empty flow has nothing to audit.

Source

Thrown at core/user-flow.js:316

 * @param {LH.UserFlow.GatherStep[]} gatherSteps
 * @return {string}
 */
function getFlowName(name, gatherSteps) {
  if (name) return name;

  const firstArtifacts = gatherSteps[0].artifacts;
  const {locale} = firstArtifacts.settings;
  const url = new URL(firstArtifacts.URL.finalDisplayedUrl).hostname;
  return translate(UIStrings.defaultFlowName, {url}, locale);
}

/**
 * @param {Array<LH.UserFlow.GatherStep>} gatherSteps
 * @param {{name?: string, config?: LH.Config, gatherStepRunnerOptions?: GatherStepRunnerOptions}} options
 */
async function auditGatherSteps(gatherSteps, options) {
  if (!gatherSteps.length) {
    throw new Error('Need at least one step before getting the result');
  }

  /** @type {LH.FlowResult['steps']} */
  const steps = [];
  for (const gatherStep of gatherSteps) {
    const {artifacts, flags} = gatherStep;
    const name = getStepName(flags, artifacts);

    let runnerOptions = options.gatherStepRunnerOptions?.get(gatherStep);

    // If the gather step is not active, we must recreate the runner options.
    if (!runnerOptions) {
      // Step specific configs take precedence over a config for the entire flow.
      const config = options.config;
      const {gatherMode} = artifacts.GatherContext;
      const {resolvedConfig} = await initializeConfig(gatherMode, config, flags);
      runnerOptions = {
        resolvedConfig,

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Ensure at least one step is added before calling createFlowResult() — call navigate(), startTimespan()/endTimespan(), or snapshot() at least once
2. Track step count in your code and guard the result call
3. If loading from saved artifacts, verify gatherSteps array is non-empty before calling auditGatherSteps

Example fix

// before — no steps added
const flow = new UserFlow(page);
const result = await flow.createFlowResult(); // throws

// after — add at least one step
const flow = new UserFlow(page);
await flow.navigate('https://example.com');
const result = await flow.createFlowResult();

// Check that at least one step exists before requesting results
if (flow._gatherSteps.length === 0) {
  throw new Error('Add at least one step (navigate/timespan/snapshot) before getting results');
}
const result = await flow.createFlowResult();

When it happens

Trigger: Calling flow.createFlowResult() or flow.generateReport() without having added any steps via navigate(), startTimespan()/endTimespan(), or snapshot(). Also reachable when calling auditGatherSteps directly with an empty array (e.g., from createArtifactsJson output with no gatherSteps).

Common situations: Empty flow — created a UserFlow but never added steps. Conditional logic that skipped all step calls (e.g., a loop that didn't iterate). Loading artifacts from createArtifactsJson where gatherSteps was empty. Forgot to call any gathering method before requesting results.

Related errors

• Please provide a url
• Invalid value: Argument must be a string or a boolean
• Invalid values. Argument 'output' must be an array from choi
• "${str}" is not a valid 'output' value. Argument 'output' mu
• --output-path (${value}) cannot be written to

AI-assisted analysis of GoogleChrome/lighthouse@9515cd4e58 (2026-08-13). Data as JSON: /api/errors/99555dca3fedd5cb. Report an issue: GitHub.