GoogleChrome/lighthouse · error · Error

configPath must be an absolute path

Error message

configPath must be an absolute path

What it means

Thrown by resolveWorkingCopy in config.js. When you pass a configPath in the run context, it must be an absolute filesystem path (path.isAbsolute). Lighthouse needs an absolute path to resolve the config directory for relative audit/gatherer paths. A relative path like './my-config.js' is rejected.

Source

Thrown at core/config/config.js:60

 * The default priority should be 0.
 * TODO: Make this an official part of the config or design a different solution.
 * @type {Record<string, number|undefined>}
 */
const internalArtifactPriorities = {
  FullPageScreenshot: 1,
  BFCacheFailures: 1,
};

/**
 * @param {LH.Config|undefined} config
 * @param {{configPath?: string}} context
 * @return {{configWorkingCopy: LH.Config, configDir?: string, configPath?: string}}
 */
function resolveWorkingCopy(config, context) {
  let {configPath} = context;

  if (configPath && !path.isAbsolute(configPath)) {
    throw new Error('configPath must be an absolute path');
  }

  if (!config) {
    config = defaultConfig;
    configPath = defaultConfigPath;
  }

  // The directory of the config path, if one was provided.
  const configDir = configPath ? path.dirname(configPath) : undefined;

  return {
    configWorkingCopy: deepCloneConfigJson(config),
    configPath,
    configDir,
  };
}

/**

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Resolve to an absolute path before passing: configPath: path.resolve(process.cwd(), './my-config.js').
2. Use __dirname-relative resolution: path.resolve(__dirname, 'config.js').
3. If invoking the CLI, pass an absolute path or rely on the CLI to resolve it.

Example fix

// before
const flags = {configPath: './config/my-config.js'};
await lighthouse(url, flags);
// after
const path = require('path');
const flags = {configPath: path.resolve(__dirname, 'config/my-config.js')};
await lighthouse(url, flags);

const path = require('path');
if (flags.configPath && !path.isAbsolute(flags.configPath)) {
  flags.configPath = path.resolve(process.cwd(), flags.configPath);
}

const path = require('path');
function isAbsolutePath(p) { return typeof p === 'string' && path.isAbsolute(p); }

try { await lighthouse(url, flags); }
catch (e) { if (/configPath must be an absolute path/.test(e.message)) flags.configPath = path.resolve(flags.configPath); throw e; }

When it happens

Trigger: Calling flags.configPath = './lighthouse-config.js' or configPath: 'config/custom.js'. path.isAbsolute returns false, so config.js:60 throws. Common when building the path with a relative string instead of path.resolve(__dirname, ...).

Common situations: CLI/programmatic usage passing a relative config path. Reading configPath from user input or a relative env var. Cross-platform issues where a path that is absolute on one OS is treated as relative.

Related errors

• ${pluginName} has an invalid category description.
• ${pluginName} has an invalid category manualDescription.
• ${pluginName} supportedModes must be an array, valid array v
• ${pluginName} groups json is not defined as an object.
• ${pluginName} has a group not defined as an object.

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