mochajs/mocha · error · TypeError

ERR_MOCHA_INVALID_ARG_TYPE

ERR_MOCHA_INVALID_ARG_TYPE

Error message

Argument '${extensions}' required when argument '${filepath}' is a directory

What it means

When `lookupFiles` is given a directory, it needs a list of file extensions to decide which files inside the directory are test files. If the `extensions` argument is missing or an empty array while `filepath` is a directory, it throws a custom ERR_MOCHA_INVALID_ARG_TYPE error stating that extensions are required.

Source

Thrown at lib/cli/lookup-files.js:134

  // Handle directory
  fs.readdirSync(filepath).forEach((dirent) => {
    const pathname = path.join(filepath, dirent);
    let stat;

    try {
      stat = fs.statSync(pathname);
      if (stat.isDirectory()) {
        if (recursive) {
          files.push(...lookupFiles(pathname, extensions, recursive));
        }
        return;
      }
    } catch {
      return;
    }
    if (!extensions.length) {
      throw createMissingArgumentError(
        `Argument '${extensions}' required when argument '${filepath}' is a directory`,
        "extensions",
        "array",
      );
    }

    if (
      !stat.isFile() ||
      !hasMatchingExtname(pathname, extensions) ||
      isHiddenOnUnix(pathname)
    ) {
      return;
    }
    files.push(pathname);
  });

  return files;
}

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Pass a non-empty array of extensions, e.g. `lookupFiles('./test', ['js'], true)`
2. Fix config loading so `extension` from .mocharc/CLI reaches the call as a populated array
3. If the path might be a file, pass extensions anyway or branch on `fs.statSync(filepath).isDirectory()` first
4. Catch by `err.code === 'ERR_MOCHA_INVALID_ARG_TYPE'` and surface which argument was invalid

Example fix

// before
lookupFiles('./test');
// after
lookupFiles('./test', ['js', 'cjs', 'mjs'], true);

const fs = require('fs');
function safeLookupFiles(filepath, extensions, recursive) {
  if (fs.statSync(filepath).isDirectory() && (!Array.isArray(extensions) || !extensions.length)) {
    throw new TypeError('extensions (non-empty array) required when filepath is a directory');
  }
  return lookupFiles(filepath, extensions, recursive);
}

const hasExtensions = (ext) => Array.isArray(ext) && ext.length > 0;

try {
  lookupFiles(filepath, extensions, recursive);
} catch (err) {
  if (err.code === 'ERR_MOCHA_INVALID_ARG_TYPE') {
    console.error('Provide a non-empty extensions array for directory arguments');
  } else throw err;
}

When it happens

Trigger: `lookupFiles('./test')` with no extensions argument; `lookupFiles('./test', [])` with an empty array; programmatic callers forwarding user config where the extension list was never populated.

Common situations: Plugin/custom-runner authors calling the internal CLI lookup directly; config parsing that drops the `extension` array from .mocharc so an empty list reaches lookupFiles; confusion between literal file arguments (extensions optional) and directory arguments (required).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ERR_MOCHA_INVALID_ARG_VALUE
• ERR_MOCHA_NO_FILES_MATCH_PATTERN
• Not enough non-option arguments: got 0, need at least 1
• Not enough arguments following: ${name}
• Invalid argument; expected a non-empty object

AI-assisted analysis of mochajs/mocha@6bcbee4fd9 (2026-09-01). Data as JSON: /api/errors/9ea37f9f0d2ad6b0. Report an issue: GitHub.