GoogleChrome/lighthouse · error · Error

Unsupported gather mode

Error message

Unsupported gather mode

What it means

Thrown by getStepName() when generating a display name for a flow step. It switches on artifacts.GatherContext.gatherMode, supporting 'navigation', 'timespan', and 'snapshot'. Any other value — including undefined, null, or a future gather mode — hits the default branch and throws. This is an internal invariant: all gather steps should have a valid gatherMode set by the gatherer runners.

Source

Thrown at core/user-flow.js:292

/**
 * @param {LH.UserFlow.StepFlags|undefined} flags
 * @param {LH.Artifacts} artifacts
 * @return {string}
 */
function getStepName(flags, artifacts) {
  if (flags?.name) return flags.name;

  const {locale} = artifacts.settings;
  const shortUrl = shortenUrl(artifacts.URL.finalDisplayedUrl);
  switch (artifacts.GatherContext.gatherMode) {
    case 'navigation':
      return translate(UIStrings.defaultNavigationName, {url: shortUrl}, locale);
    case 'timespan':
      return translate(UIStrings.defaultTimespanName, {url: shortUrl}, locale);
    case 'snapshot':
      return translate(UIStrings.defaultSnapshotName, {url: shortUrl}, locale);
    default:
      throw new Error('Unsupported gather mode');
  }
}

/**
 * @param {string|undefined} name
 * @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);
}

/**

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Create flow steps only through the UserFlow API (navigate/startTimespan+endTimespan/snapshot) which sets GatherContext correctly
2. If loading saved artifacts, validate each step's artifacts.GatherContext.gatherMode is one of the three supported values before calling createFlowResult
3. Ensure you're using a compatible Lighthouse version for both gathering and auditing

const VALID_MODES = ['navigation', 'timespan', 'snapshot'];
for (const step of gatherSteps) {
  const mode = step.artifacts?.GatherContext?.gatherMode;
  if (!VALID_MODES.includes(mode)) {
    throw new Error(`Invalid gather mode: ${mode} — steps must be created via the UserFlow API`);
  }
}

/** @param {string} mode @returns {boolean} */
function isValidGatherMode(mode) {
  return mode === 'navigation' || mode === 'timespan' || mode === 'snapshot';
}

When it happens

Trigger: Called from auditGatherSteps (user-flow.js:323) during createFlowResult(). Fires when a gather step's artifacts.GatherContext.gatherMode is not 'navigation', 'timespan', or 'snapshot'. This can occur with manually constructed gather steps (e.g., from createArtifactsJson deserialization with corrupted data), mocked test artifacts, or artifacts from an incompatible Lighthouse version that introduced a new gather mode.

Common situations: Manually constructing gather steps without proper GatherContext. Deserializing artifacts from a flow saved by a different Lighthouse version. Test mocks with incomplete artifacts.GatherContext. Corrupted or hand-edited flow artifacts JSON.

Related errors

• ${pluginName} supportedModes must be an array, valid array v
• Gatherer for ${artifactDefn.id} did not support any gather m
• Timespan already in progress
• Navigation already in progress
• No navigation in progress

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