yarnpkg/yarn · error · MessageError

Outdated lockfile. Please run `yarn install` and try again.

Error message

Outdated lockfile. Please run `yarn install` and try again.

What it means

During dependency walk, lockfile.getLocked(pattern) returns null for a pattern that should have a lockfile entry. This means package.json declares a dependency whose pattern is absent from yarn.lock — the lockfile is stale relative to package.json.

Source

Thrown at src/package-request.js:409

    // filter the list down to just the packages requested.
    // prevents us from having to query the metadata for all packages.
    if ((filterByPatterns && filterByPatterns.length) || (flags && flags.pattern)) {
      const filterByNames =
        filterByPatterns && filterByPatterns.length
          ? filterByPatterns.map(pattern => normalizePattern(pattern).name)
          : [];
      depReqPatterns = depReqPatterns.filter(
        dep =>
          filterByNames.indexOf(normalizePattern(dep.pattern).name) >= 0 ||
          (flags && flags.pattern && micromatch.contains(normalizePattern(dep.pattern).name, flags.pattern)),
      );
    }

    const deps = await Promise.all(
      depReqPatterns.map(async ({pattern, hint, workspaceName, workspaceLoc}): Promise<Dependency> => {
        const locked = lockfile.getLocked(pattern);
        if (!locked) {
          throw new MessageError(reporter.lang('lockfileOutdated'));
        }

        const {name, version: current} = locked;
        let latest = '';
        let wanted = '';
        let url = '';

        const normalized = normalizePattern(pattern);

        if (getExoticResolver(pattern) || getExoticResolver(normalized.range)) {
          latest = wanted = 'exotic';
          url = normalized.range;
        } else {
          const registry = config.registries[locked.registry];

          ({latest, wanted, url} = await registry.checkOutdated(config, name, normalized.range));
        }

View on GitHub (pinned to c2dda503f3)

Solutions

Run yarn install to regenerate yarn.lock
If corruption persists, delete yarn.lock and run yarn install fresh
Ensure yarn.lock is committed and kept in sync after every package.json change

Defensive patterns

Strategy: validation

Validate before calling

// Before running install, verify lockfile coverage
const lockfileObj = await lockfile.parseLockfile(filePath);
const declaredDeps = Object.keys(pkgJson.dependencies || {});
const missing = declaredDeps.filter(d => !lockfileObj[d] && !lockfile.getLocked(d));
if (missing.length) {
  console.warn('Lockfile is stale; patterns missing:', missing);
}

Type guard

function isLockfileComplete(lockfile: object, patterns: string[]): boolean {
  return patterns.every(p => lockfile.getLocked(p) != null);
}

Try / catch

try {
  await install(config);
} catch (e) {
  if (e.message.includes('Outdated lockfile')) {
    // run yarn install --force to regenerate
  }
}

Prevention

Run yarn install whenever package.json changes
Never hand-edit yarn.lock
Keep yarn.lock under version control and resolve merge conflicts promptly

When it happens

Trigger: package.json was edited (deps added/changed/renamed) without regenerating yarn.lock, so a required pattern has no locked entry. getLocked returns falsy.

Common situations: Merging branches with conflicting yarn.lock changes; hand-editing yarn.lock; upgrading deps without running install; CI running outdated lockfile.

Related errors

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