What causes "Usage $0 " in GoogleChrome/lighthouse?

Run from the correct working directory (the script resolves paths relative to cwd)

Usage $0 <expectations file>

Error message

Usage $0 <expectations file>

What it means

Usage guard in run-on-all-assets.js. The script reads a golden expectations JSON file containing site definitions with trace and devtools log paths. If the resolved path does not exist on disk, it cannot locate the trace files to compute Lantern metrics from.

Source

Thrown at core/scripts/lantern/run-on-all-assets.js:38

import fs from 'fs';
import os from 'os';
import path from 'path';
import childProcess from 'child_process';
import util from 'util';

import constants from './constants.js';
import {LH_ROOT} from '../../../shared/root.js';
import {readJson} from '../../test/test-utils.js';
import {ConcurrentMapper} from '../../../cli/test/smokehouse/lib/concurrent-mapper.js';

const execFile = util.promisify(childProcess.execFile);

const INPUT_PATH = process.argv[2] || constants.SITE_INDEX_WITH_GOLDEN_PATH;
const SITE_INDEX_PATH = path.resolve(process.cwd(), INPUT_PATH);
const SITE_INDEX_DIR = path.dirname(SITE_INDEX_PATH);
const RUN_ONCE_PATH = path.join(LH_ROOT, 'core/scripts/lantern/run-once.js');

if (!fs.existsSync(SITE_INDEX_PATH)) throw new Error('Usage $0 <expectations file>');

/** @type {Golden} */
const expectations = readJson(SITE_INDEX_PATH);

const concurrency = process.env.CI ?
  os.cpus().length :
  Math.max(os.cpus().length - 2, 1);
console.log(`Running across ${concurrency} processes ...`);

await ConcurrentMapper.map(expectations.sites, async (site) => {
  const trace = path.join(SITE_INDEX_DIR, site.unthrottled.tracePath);
  const log = path.join(SITE_INDEX_DIR, site.unthrottled.devtoolsLogPath);

  console.log('Running', site.url, '...');
  try {
    const rawOutput = (await execFile(RUN_ONCE_PATH, [trace, log])).stdout.trim();
    if (!rawOutput) console.log(site.url, 'ERROR EMPTY OUTPUT!');
    const lantern = JSON.parse(rawOutput);

View on GitHub (pinned to 9515cd4e58)

Solutions

Run from the correct working directory (the script resolves paths relative to cwd)
Verify the default file exists: check ./lantern-data/site-index-plus-golden-expectations.json relative to your cwd
Pass the correct absolute path as argv[2] if running from a different directory

Defensive patterns

Strategy: validation

Validate before calling

if (!fs.existsSync(SITE_INDEX_PATH)) {
  console.error(`File not found: ${SITE_INDEX_PATH}`);
  console.error('Run from the lantern/ directory or pass an absolute path');
  process.exit(1);
}

Prevention

Run from the working directory where the site index path resolves correctly
Pass an absolute path as argv[2] if unsure of cwd
Verify the lantern-data directory exists in your checkout

When it happens

Trigger: Running run-on-all-assets.js when the site index file doesn't exist at the resolved path. The default path is './lantern-data/site-index-plus-golden-expectations.json' (relative to cwd). A custom path passed as argv[2] that doesn't exist also triggers it.

Common situations: Running from the wrong working directory — the default path is relative to process.cwd(), so running from repo root instead of the lantern directory (or vice versa) resolves to a non-existent file. Fresh clone missing the lantern-data directory. File was renamed or moved in a version update.

Related errors

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