GoogleChrome/lighthouse · error · Error

Please provide a url

Error message

Please provide a url

What it means

Lighthouse's yargs parser uses a .check() handler to enforce that a target URL is provided before any audit work begins. The check allows several bypass conditions — listing audits (--list-all-audits), listing locales (--list-locales), listing trace categories (--list-trace-categories), or processing saved artifacts (--audit-mode without --gather-mode). If none of those bypass conditions are met and no positional argument (the URL) is present, this error halts the program.

Source

Thrown at cli/cli-flags.js:322

    .choices('form-factor', /** @type {const} */ (['mobile', 'desktop']))
    .choices('throttling-method', /** @type {const} */ (['devtools', 'provided', 'simulate']))
    .choices('preset', /** @type {const} */ (['perf', 'experimental', 'desktop']))

    .check(argv => {
      // Lighthouse doesn't need a URL if...
      //   - We're just listing the available options.
      //   - We're just printing the config.
      //   - We're in auditMode (and we have artifacts already)
      // If one of these don't apply, if no URL, stop the program and ask for one.
      const isPrintSomethingMode = argv.listAllAudits || argv.listLocales || argv.listTraceCategories;
      const isOnlyAuditMode = !!argv.auditMode && !argv.gatherMode;
      if (isPrintSomethingMode || isOnlyAuditMode) {
        return true;
      } else if (argv._.length > 0) {
        return true;
      }

      throw new Error('Please provide a url');
    })
    .epilogue('For more information on Lighthouse, see https://developers.google.com/web/tools/lighthouse/.')
    .wrap(y.terminalWidth());
}

/**
 * @param {string=} manualArgv
 * @param {{noExitOnFailure?: boolean}=} options
 * @return {LH.CliFlags}
 */
function getFlags(manualArgv, options = {}) {
  let parser = getYargsParser(manualArgv);

  if (options.noExitOnFailure) {
    // Silence console.error() logging and don't process.exit().
    // `parser.fail(false)` can be used in yargs once v17 is released.
    parser = parser.fail((msg, err) => {
      if (err) throw err;

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Add the target URL as the final positional argument: lighthouse https://example.com
2. If your shell variable may be empty, guard it: [ -n "$TARGET_URL" ] && lighthouse "$TARGET_URL"
3. If you intended to list audits or locales, add the appropriate flag: lighthouse --list-all-audits
4. If processing saved artifacts, ensure --audit-mode is set without --gather-mode: lighthouse --audit-mode=./artifacts

Example fix

# before
lighthouse --output=json
# after
lighthouse https://example.com --output=json

// Validate URL is present before calling Lighthouse
function validateArgs(args) {
  const hasUrl = args.some(arg => arg.startsWith('http')) ||
    (args.length > 0 && !args.every(a => a.startsWith('--')));
  if (!hasUrl) {
    console.error('Error: A URL is required. Usage: lighthouse <url> [options]');
    process.exit(1);
  }
}

When it happens

Trigger: Running the Lighthouse CLI with zero positional arguments and none of the bypass flags. Specifically: argv._.length === 0 (no positional URL), isPrintSomethingMode is false (no --list-all-audits/--list-locales/--list-trace-categories), and isOnlyAuditMode is false (no --audit-mode, or --audit-mode combined with --gather-mode).

Common situations: Forgetting the URL entirely; shell variable expansion producing an empty string (lighthouse "$URL" where URL is unset); quoting issues that consume the positional argument; migrating a script that previously read the URL from a different position.

Related errors

• 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
• Invalid value: Argument 'locale' must be a string

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