mochajs/mocha · error · Error

ERR_MOCHA_UNPARSABLE_FILE

ERR_MOCHA_UNPARSABLE_FILE

Error message

Unable to read ${filepath}: ${err}

What it means

loadPkgRc reads a package.json (default ./package.json or one given via --package) to extract a `mocha` config key. If reading the explicitly-specified package file fails, Mocha throws ERR_MOCHA_UNPARSABLE_FILE. A missing default ./package.json is silently ignored; only an explicitly requested file that cannot be read raises this error.

Source

Thrown at lib/cli/options.cjs:92

 * @public
 * @alias module:lib/cli.loadPkgRc
 * @returns {external:parseArgs.Arguments|void} Parsed config. Throws if unparsableF. Empty object if file not found.
 */
const loadPkgRc = (args = {}) => {
  let result;
  if (args.package === false) {
    return result;
  }
  result = {};
  const filepath = args.package || sync(mocharc.package);
  if (filepath) {
    let configData;
    try {
      configData = readFileSync(filepath, "utf8");
    } catch (err) {
      // If `args.package` was explicitly specified, throw an error
      if (filepath == args.package) {
        throw createUnparsableFileError(
          `Unable to read ${filepath}: ${err}`,
          filepath,
        );
      } else {
        debug("failed to read default package.json at %s; ignoring", filepath);
        return result;
      }
    }
    try {
      const pkg = JSON.parse(configData);
      if (pkg.mocha) {
        debug("`mocha` prop of package.json parsed: %O", pkg.mocha);
        result = pkg.mocha;
      } else {
        debug("no config found in %s", filepath);
      }
    } catch (err) {
      // If JSON failed to parse, throw an error.

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Correct the --package path (verify with ls from the cwd mocha runs in).
2. Ensure the file is readable (check permissions, and that it exists in the container/CI workspace).
3. Remove --package if you actually want the default ./package.json behavior (missing default is ignored).
4. Use an absolute path in CI to avoid cwd drift.

Example fix

// before
npx mocha --package ./conf/pakage.json
// after
npx mocha --package ./config/package.json

const fs = require('fs');
const pkgPath = './config/package.json';
if (!fs.existsSync(pkgPath)) {
  throw new Error(`--package target missing: ${require('path').resolve(pkgPath)}`);
}

function isReadableFile(p) {
  try { require('fs').accessSync(p); return require('fs').statSync(p).isFile(); } catch { return false; }
}

try {
  execSync('npx mocha --package ' + pkgPath, {stdio: 'inherit'});
} catch (err) {
  if (String(err.stderr).includes('Unable to read')) {
    console.error(`Check that ${pkgPath} exists and is readable from the mocha cwd`);
  }
}

When it happens

Trigger: Running `mocha --package ./config/pkg.json` (or MOCHA_OPTIONS/programmatic loadPkgRc with args.package) where that file does not exist or is unreadable (permissions, wrong path).

Common situations: Typo in --package path; file deleted or moved after CI config was written; running mocha from a different cwd so relative path resolves wrong; restricted CI permissions.

Related errors

• ERR_MOCHA_UNPARSABLE_FILE
• Not enough non-option arguments: got 0, need at least 1
• Not enough arguments following: ${name}
• Warning: ${warning.message}
• ERR_MOCHA_NO_FILES_MATCH_PATTERN

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