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.

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 'extra-headers' must be a string
• Invalid value: Argument 'locale' must be a string
• Invalid value: Argument must be a string or a boolean
• Invalid value: Argument 'screenEmulation' must be an…
• Invalid value: Argument 'throttling' must be an object…

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

Appendix: 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)