yarnpkg/yarn · error · MessageError

Your project root defines workspaces but the feature is disa

Error message

Your project root defines workspaces but the feature is disabled in your Yarn config. Please check "workspaces-experimental" in your .yarnrc file.

What it means

Thrown at the end of `config.init` when `workspaceRootFolder` was found (an ancestor package.json declares `workspaces`) but `workspacesEnabled` is false. Workspaces are gated by the `workspaces-experimental` option; if it is explicitly set to `false` in .yarnrc the feature is disabled, and a project that declares workspaces becomes a contradiction Yarn refuses to proceed with.

Source

Thrown at src/config.js:447

    //init & create cacheFolder, tempFolder
    this.cacheFolder = path.join(this._cacheRootFolder, 'v' + String(constants.CACHE_VERSION));
    this.tempFolder = opts.tempFolder || path.join(this.cacheFolder, '.tmp');
    await fs.mkdirp(this.cacheFolder);
    await fs.mkdirp(this.tempFolder);

    if (opts.production !== undefined) {
      this.production = Boolean(opts.production);
    } else {
      this.production =
        Boolean(this.getOption('production')) ||
        (process.env.NODE_ENV === 'production' &&
          process.env.NPM_CONFIG_PRODUCTION !== 'false' &&
          process.env.YARN_PRODUCTION !== 'false');
    }

    if (this.workspaceRootFolder && !this.workspacesEnabled) {
      throw new MessageError(this.reporter.lang('workspacesDisabled'));
    }
  }

  _init(opts: ConfigOptions) {
    this.registryFolders = [];
    this.linkedModules = [];

    this.registries = map();
    this.cache = map();

    // Ensure the cwd is always an absolute path.
    this.cwd = path.resolve(opts.cwd || this.cwd || process.cwd());

    this.looseSemver = opts.looseSemver == undefined ? true : opts.looseSemver;

    this.commandName = opts.commandName || '';

    this.enableDefaultRc = opts.enableDefaultRc !== false;

View on GitHub (pinned to c2dda503f3)

Solutions

1. Remove `workspaces-experimental false` from your .yarnrc (~/.yarnrc or project-level .yarnrc).
2. Set `workspaces-experimental true` explicitly, or simply omit the key (default is enabled).
3. Search all .yarnrc files in the chain: `yarn config ls` to see effective values.

Example fix

# before (.yarnrc)
workspaces-experimental false
# after
# (delete the line, or set to true)
workspaces-experimental true

// Before init, check that workspaces are not disabled when a root declares workspaces.
const workspacesEnabled = config.getOption('workspaces-experimental') !== false;
if (rootManifest && rootManifest.workspaces && !workspacesEnabled) {
  console.error('Enable workspaces: remove "workspaces-experimental false" from .yarnrc');;
  process.exit(1);
}

try {
  await config.init(opts);
} catch (err) {
  if (err.message.includes('workspaces-experimental')) {
    reporter.error('Set workspaces-experimental true in .yarnrc or remove the setting.');
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: An ancestor .yarnrc or user-level ~/.yarnrc contains `workspaces-experimental false`, while a package.json in the project chain declares a `workspaces` field.

Common situations: An old .yarnrc from when workspaces were unstable disabled the feature, and the project later adopted workspaces. A global ~/.yarnrc sets it off for all projects. Corporate shared config disables experimental features.

Related errors

• workspaceRootNotFound
• workspaceRootNotFound
• The workspaces field in package.json must be an array.
• workspacesAddRootCheck
• workspacesRemoveRootCheck

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