What causes "--output-path (${value}) cannot be written to" in GoogleChrome/lighthouse?

Create the target directory first: mkdir -p ./reports && lighthouse --output-path=./reports/report.json

GoogleChrome/lighthouse · error · Error

--output-path (${value}) cannot be written to

Error message

--output-path (${value}) cannot be written to

What it means

The --output-path flag specifies where Lighthouse writes its report. coerceOutputPath validates that the value is a non-empty string and that the parent directory (path.dirname) exists on the filesystem. This prevents Lighthouse from failing later during the write phase.

Source

Thrown at cli/cli-flags.js:416

    if (!outputTypes.includes(str)) {
      throw new Error(`"${str}" is not a valid 'output' value. ` + errorHint);
    }
    return true;
  });

  return validValues;
}

/**
 * Verifies outputPath is something we can actually write to.
 * @param {unknown=} value
 * @return {string=}
 */
function coerceOutputPath(value) {
  if (value === undefined) return;

  if (typeof value !== 'string' || !value || !fs.existsSync(path.dirname(value))) {
    throw new Error(`--output-path (${value}) cannot be written to`);
  }

  return value;
}

/**
 * Verifies value is a string, then coerces type to LH.Locale for convenience. However, don't
 * allowlist specific locales. Why? So we can support the user who requests 'es-MX' (unsupported)
 * and we'll fall back to 'es' (supported).
 * @param {unknown} value
 * @return {LH.Locale|undefined}
 */
function coerceLocale(value) {
  if (value === undefined) return;

  if (typeof value !== 'string') throw new Error(`Invalid value: Argument 'locale' must be a string`);
  return /** @type {LH.Locale} */ (value);
}

View on GitHub (pinned to 9515cd4e58)

Solutions

Create the target directory first: mkdir -p ./reports && lighthouse --output-path=./reports/report.json
Verify the path is correct and the parent directory exists: ls -la $(dirname your/path)
Use stdout to avoid filesystem issues: --output-path=stdout (valid for JSON output)

Example fix

# before
lighthouse --output-path=/tmp/nonexistent/report.json https://example.com
# after
mkdir -p /tmp/reports && lighthouse --output-path=/tmp/reports/report.json https://example.com

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
const path = require('path');
function validateOutputPath(outputPath) {
  if (typeof outputPath !== 'string' || !outputPath) {
    throw new Error('outputPath must be a non-empty string');
  }
  const dir = path.dirname(outputPath);
  if (!fs.existsSync(dir)) {
    throw new Error(`Parent directory does not exist: ${dir}`);
  }
  return true;
}

Prevention

Always mkdir -p the output directory before running Lighthouse
Use absolute paths to avoid working-directory ambiguity
For JSON output, consider --output-path=stdout to avoid filesystem issues entirely

When it happens

Trigger: Passing --output-path with a value that is undefined (but somehow not caught earlier), an empty string, or a path whose parent directory does not exist. For example: --output-path=/nonexistent/dir/report.json where /nonexistent/dir does not exist.

Common situations: Typo in the directory path; pointing to a directory that hasn't been created yet; relative path resolved from an unexpected working directory; trailing slash causing dirname to resolve unexpectedly.

Related errors

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