yarnpkg/yarn · error · MessageError

noRequiredLockfile

Error message

noRequiredLockfile

What it means

Thrown during CLI startup after `config.init` completes. When a command declares `requireLockfile: true` (e.g. `yarn install --frozen-lockfile`, `yarn check`, `yarn pack` in CI), Yarn checks that `yarn.lock` exists in `config.lockfileFolder`. If the file is absent the command aborts because it cannot proceed deterministically without a lockfile.

Source

Thrown at src/cli/index.js:561

      ignoreEngines: commander.ignoreEngines,
      ignoreScripts: commander.ignoreScripts,
      offline: commander.preferOffline || commander.offline,
      looseSemver: !commander.strictSemver,
      production: commander.production,
      httpProxy: commander.proxy,
      httpsProxy: commander.httpsProxy,
      registry: commander.registry,
      networkConcurrency: commander.networkConcurrency,
      networkTimeout: commander.networkTimeout,
      nonInteractive: commander.nonInteractive,
      updateChecksums: commander.updateChecksums,
      focus: commander.focus,
      otp: commander.otp,
    })
    .then(() => {
      // lockfile check must happen after config.init sets lockfileFolder
      if (command.requireLockfile && !fs.existsSync(path.join(config.lockfileFolder, constants.LOCKFILE_FILENAME))) {
        throw new MessageError(reporter.lang('noRequiredLockfile'));
      }

      // option "no-progress" stored in yarn config
      const noProgressConfig = config.registries.yarn.getOption('no-progress');

      if (noProgressConfig) {
        reporter.disableProgress();
      }

      // verbose logs outputs process.uptime() with this line we can sync uptime to absolute time on the computer
      reporter.verbose(`current time: ${new Date().toISOString()}`);

      const mutex: mixed = commander.mutex;
      if (mutex && typeof mutex === 'string') {
        const separatorLoc = mutex.indexOf(':');
        let mutexType;
        let mutexSpecifier;
        if (separatorLoc === -1) {

View on GitHub (pinned to c2dda503f3)

Solutions

  1. Run `yarn install` once without `--frozen-lockfile` to generate yarn.lock, then commit it.
  2. Ensure yarn.lock is tracked in version control (remove it from .gitignore).
  3. If the lockfile was deleted, restore it from git: `git checkout -- yarn.lock`.
  4. Drop the `--frozen-lockfile` / `requireLockfile` flag for the first install on a clean environment.

Example fix

# before (CI step, fails on fresh checkout)
yarn install --frozen-lockfile
# after (generate lockfile first, then freeze)
yarn install
git add yarn.lock
# subsequent CI runs:
yarn install --frozen-lockfile
Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
const path = require('path');
const lockfilePath = path.join(config.lockfileFolder, 'yarn.lock');
if (command.requireLockfile && !fs.existsSync(lockfilePath)) {
  // generate lockfile first instead of failing
  console.error('yarn.lock missing — run `yarn install` without --frozen-lockfile first.');
  process.exit(1);
}

Try / catch

try {
  await runCommand();
} catch (err) {
  if (err instanceof MessageError && err.message === reporter.lang('noRequiredLockfile')) {
    // fall back to a non-frozen install to generate the lockfile
    await exec('yarn install');
  } else {
    throw err;
  }
}

Prevention

When it happens

Trigger: Running any command whose `Command` definition sets `requireLockfile = true` in a directory that has never had `yarn install` run (no yarn.lock generated yet). Also `--frozen-lockfile` in a fresh CI checkout before the lockfile is committed.

Common situations: CI pipeline runs `yarn install --frozen-lockfile` but yarn.lock was gitignored or never committed. A fresh clone with no prior install. A command like `yarn check` run before the first `yarn install`.

Related errors

AI-assisted analysis of yarnpkg/yarn@c2dda503f3 (2026-08-13). Data as JSON: /api/errors/833b4247ceb90fe6. Report an issue: GitHub.