{"record":{"id":"0dc6477260ac9d63","repo":"yarnpkg/yarn","slug":"the-package-0-requires-a-flat-dependency-graph-a","errorCode":null,"errorMessage":"The package $0 requires a flat dependency graph. Add `\"flat\": true` to your package.json and try again.","messagePattern":"The package \\$0 requires a flat dependency graph\\. Add `\"flat\": true` to your package\\.json and try again\\.","errorType":"exception","errorClass":"MessageError","httpStatus":null,"severity":"error","filePath":"src/package-request.js","lineNumber":264,"sourceCode":"      // swallow warnings\n    });\n\n    // check if while we were resolving this dep we've already resolved one that satisfies\n    // the same range\n    const {range, name} = normalizePattern(this.pattern);\n    const solvedRange = semver.validRange(range) ? info.version : range;\n    const resolved: ?Manifest =\n      !info.fresh || frozen\n        ? this.resolver.getExactVersionMatch(name, solvedRange, info)\n        : this.resolver.getHighestRangeVersionMatch(name, solvedRange, info);\n\n    if (resolved) {\n      this.resolver.reportPackageWithExistingVersion(this, info);\n      return;\n    }\n\n    if (info.flat && !this.resolver.flat) {\n      throw new MessageError(this.reporter.lang('flatGlobalError', `${info.name}@${info.version}`));\n    }\n\n    // validate version info\n    PackageRequest.validateVersionInfo(info, this.reporter);\n\n    //\n    const remote = info._remote;\n    invariant(remote, 'Missing remote');\n\n    // set package reference\n    const ref = new PackageReference(this, info, remote);\n    ref.addPattern(this.pattern, info);\n    ref.addOptional(this.optional);\n    ref.setFresh(fresh);\n    info._reference = ref;\n    info._remote = remote;\n    // start installation of dependencies\n    const promises = [];","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/yarnpkg/yarn/blob/c2dda503f3759b5be5f0e24ecd9cf5c97a540147/src/package-request.js#L246-L282","documentation":"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.","triggerScenarios":"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.","commonSituations":"Upgrading a dependency that newly requires flat mode; pulling in a transitive dep that demands flat resolution; monorepo projects that deliberately avoid flat mode.","solutions":["Add \"flat\": true to your root package.json and run yarn install again","Downgrade the offending dependency to a version that does not require flat mode","Use the resolutions field to pin versions if enabling flat mode globally is undesirable"],"exampleFix":"// before (package.json)\n{\n  \"name\": \"my-app\"\n}\n// after\n{\n  \"name\": \"my-app\",\n  \"flat\": true\n}","handlingStrategy":"validation","validationCode":"const depsRequiringFlat = Object.values(manifest.dependencies || {})\n  .filter(dep => getExoticResolver(dep));\n// Before install, check transitive deps for flat:true by inspecting their manifests\nif (!pkgJson.flat && someDepRequiresFlat) {\n  console.warn('A dependency requires flat mode; add \"flat\": true to package.json');\n}","typeGuard":"function requiresFlatMode(manifest: {flat?: boolean}): boolean {\n  return manifest.flat === true;\n}","tryCatchPattern":"try {\n  await request.find({fresh: true});\n} catch (e) {\n  if (e.message.includes('flat dependency graph')) {\n    // prompt user to add flat:true, then retry\n  }\n}","preventionTips":["Audit new dependencies for flat:true requirement before adding","Enable flat mode in monorepos proactively if uncertain","Lock dependency versions to avoid surprise flat requirements"],"tags":["flat-mode","dependency-graph","configuration"],"backgroundTag":null,"analyzedSha":"c2dda503f3759b5be5f0e24ecd9cf5c97a540147","analyzedAt":"2026-08-13T04:17:06.305Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}