yarnpkg/yarn · error · MessageError

The package $0 requires a flat dependency graph. Add `"flat"

Error message

The package $0 requires a flat dependency graph. Add `"flat": true` to your package.json and try again.

What it means

When a dependency's manifest declares 'flat': true but the root resolver has flat mode disabled (resolver.flat is false), Yarn throws. Flat mode enforces a single version per package; a sub-dependency can mandate it.

Source

Thrown at src/package-request.js:264

      // swallow warnings
    });

    // check if while we were resolving this dep we've already resolved one that satisfies
    // the same range
    const {range, name} = normalizePattern(this.pattern);
    const solvedRange = semver.validRange(range) ? info.version : range;
    const resolved: ?Manifest =
      !info.fresh || frozen
        ? this.resolver.getExactVersionMatch(name, solvedRange, info)
        : this.resolver.getHighestRangeVersionMatch(name, solvedRange, info);

    if (resolved) {
      this.resolver.reportPackageWithExistingVersion(this, info);
      return;
    }

    if (info.flat && !this.resolver.flat) {
      throw new MessageError(this.reporter.lang('flatGlobalError', `${info.name}@${info.version}`));
    }

    // validate version info
    PackageRequest.validateVersionInfo(info, this.reporter);

    //
    const remote = info._remote;
    invariant(remote, 'Missing remote');

    // set package reference
    const ref = new PackageReference(this, info, remote);
    ref.addPattern(this.pattern, info);
    ref.addOptional(this.optional);
    ref.setFresh(fresh);
    info._reference = ref;
    info._remote = remote;
    // start installation of dependencies
    const promises = [];

View on GitHub (pinned to c2dda503f3)

Solutions

1. Add "flat": true to your root package.json and run yarn install again
2. Downgrade the offending dependency to a version that does not require flat mode
3. Use the resolutions field to pin versions if enabling flat mode globally is undesirable

Example fix

// before (package.json)
{
  "name": "my-app"
}
// after
{
  "name": "my-app",
  "flat": true
}

const depsRequiringFlat = Object.values(manifest.dependencies || {})
  .filter(dep => getExoticResolver(dep));
// Before install, check transitive deps for flat:true by inspecting their manifests
if (!pkgJson.flat && someDepRequiresFlat) {
  console.warn('A dependency requires flat mode; add "flat": true to package.json');
}

function requiresFlatMode(manifest: {flat?: boolean}): boolean {
  return manifest.flat === true;
}

try {
  await request.find({fresh: true});
} catch (e) {
  if (e.message.includes('flat dependency graph')) {
    // prompt user to add flat:true, then retry
  }
}

When it happens

Trigger: A transitive dependency publishes with "flat": true in its package.json while the consuming project's package.json lacks "flat": true. Checked in find() after info is fetched.

Common situations: Upgrading a dependency that newly requires flat mode; pulling in a transitive dep that demands flat resolution; monorepo projects that deliberately avoid flat mode.

Related errors

• Unknown registry resolver $0
• Outdated lockfile. Please run `yarn install` and try again.
• Recursive .yarnrc files specifying --cwd flags. Bailing out.

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