yarnpkg/yarn · error · MessageError

workspacesRemoveRootCheck

Error message

workspacesRemoveRootCheck

What it means

When `yarn remove` is invoked in a workspace root (config.cwd === config.workspaceRootFolder), removing a dependency there would affect every workspace. As a guard, remove.js:39-40 throws workspacesRemoveRootCheck unless `--ignore-workspace-root-check` (-W) is passed.

Source

Thrown at src/cli/commands/remove.js:37

  commander.description('Removes a package from your direct dependencies updating your package.json and yarn.lock.');
  commander.usage('remove [packages ...] [flags]');
  commander.option('-W, --ignore-workspace-root-check', 'required to run yarn remove inside a workspace root');
}

export function hasWrapper(commander: Object, args: Array<string>): boolean {
  return true;
}

export async function run(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<void> {
  const isWorkspaceRoot = config.workspaceRootFolder && config.cwd === config.workspaceRootFolder;

  if (!args.length) {
    throw new MessageError(reporter.lang('tooFewArguments', 1));
  }

  // running "yarn remove something" in a workspace root is often a mistake
  if (isWorkspaceRoot && !flags.ignoreWorkspaceRootCheck) {
    throw new MessageError(reporter.lang('workspacesRemoveRootCheck'));
  }

  const totalSteps = args.length + 1;
  let step = 0;

  // load manifests
  const lockfile = await Lockfile.fromDirectory(config.lockfileFolder);
  const rootManifests = await config.getRootManifests();
  const manifests = [];

  for (const name of args) {
    reporter.step(++step, totalSteps, `Removing module ${name}`, emoji.get('wastebasket'));

    let found = false;

    for (const registryName of Object.keys(registries)) {
      const registry = config.registries[registryName];
      const object = rootManifests[registryName].object;

View on GitHub (pinned to c2dda503f3)

Solutions

1. Move into the specific workspace package directory and run `yarn remove <pkg>` there.
2. If you truly intend to remove the dependency from the root workspace, pass `-W` / `--ignore-workspace-root-check`.
3. Confirm your CWD with `pwd` and the workspace layout with `yarn workspaces info` before retrying.

Example fix

# before (in workspace root)
$ yarn remove lodash   # workspacesRemoveRootCheck
# after
$ cd packages/my-app && yarn remove lodash
# or, intentionally at root
$ yarn remove lodash -W

const path = require('path');
function assertNotRootUnlessAllowed(config, flags) {
  const isRoot = config.workspaceRootFolder && config.cwd === config.workspaceRootFolder;
  if (isRoot && !flags.ignoreWorkspaceRootCheck) {
    throw new Error('Refusing remove in workspace root; cd into a workspace or pass -W.');
  }
}

try {
  await runYarn(['remove', pkg]);
} catch (e) {
  if (/workspacesRemoveRootCheck/.test(e.message)) {
    console.error('Run from a workspace package, or pass -W to remove at root.');
    return;
  }
  throw e;
}

When it happens

Trigger: Running `yarn remove <pkg>` while CWD is the workspace root, without the `-W` flag.

Common situations: Being parked in the monorepo root by default; tooling that shells out from the root; forgetting which workspace you're in.

Related errors

• workspacesAddRootCheck
• publishPrivate
• tooFewArguments
• moduleNotInManifest
• installCommandRenamed

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