yarnpkg/yarn · error · MessageError

This command can only be run inside an individual workspace.

Error message

This command can only be run inside an individual workspace.

What it means

Thrown during `config.init` when the `--focus` flag is set and either no `workspaceRootFolder` was found (not inside a workspace) or `cwd === workspaceRootFolder` (you are AT the workspace root). Focus mode installs only the dependencies of one workspace plus shared deps, so it must be run from within an individual workspace sub-package, not the root.

Source

Thrown at src/config.js:260

   */

  resolveConstraints(versions: Array<string>, range: string): Promise<?string> {
    return this.constraintResolver.reduce(versions, range);
  }

  /**
   * Initialise config. Fetch registry options, find package roots.
   */

  async init(opts: ConfigOptions = {}): Promise<void> {
    this._init(opts);

    this.workspaceRootFolder = await this.findWorkspaceRoot(this.cwd);
    this.lockfileFolder = this.workspaceRootFolder || this.cwd;

    // using focus in a workspace root is not allowed
    if (this.focus && (!this.workspaceRootFolder || this.cwd === this.workspaceRootFolder)) {
      throw new MessageError(this.reporter.lang('workspacesFocusRootCheck'));
    }

    if (this.focus) {
      const focusedWorkspaceManifest = await this.readRootManifest();
      this.focusedWorkspaceName = focusedWorkspaceManifest.name;
    }

    this.linkedModules = [];

    let linkedModules;
    try {
      linkedModules = await fs.readdir(this.linkFolder);
    } catch (err) {
      if (err.code === 'ENOENT') {
        linkedModules = [];
      } else {
        throw err;
      }

View on GitHub (pinned to c2dda503f3)

Solutions

Change directory into an individual workspace package before running `yarn install --focus`.
Remove the `--focus` flag if you want a full root install.
Verify `config.cwd !== config.workspaceRootFolder` before invoking focus.

Example fix

# before (run from repo root)
yarn install --focus
# after
cd packages/my-workspace
yarn install --focus

Defensive patterns

Strategy: validation

Validate before calling

// Before running with --focus, ensure cwd is inside a workspace but not at its root.
if (config.focus) {
  if (!config.workspaceRootFolder) {
    throw new Error('--focus requires being inside an individual workspace (no workspace root found).');
  }
  if (config.cwd === config.workspaceRootFolder) {
    throw new Error('--focus must be run from a workspace sub-package, not the root.');
  }
}

Type guard

function isInsideWorkspaceNotRoot(config) {
  return Boolean(config.workspaceRootFolder) && config.cwd !== config.workspaceRootFolder;
}

Try / catch

try {
  await config.init({focus: true});
} catch (err) {
  if (err.message.includes('workspacesFocusRootCheck')) {
    console.error('cd into a workspace package before using --focus.');
    process.exit(1);
  }
  throw err;
}

Prevention

Always `cd` into the target workspace package before running `yarn install --focus`.
In monorepo task runners, assert `process.cwd() !== workspaceRoot` before adding `--focus`.
Document that --focus is a per-workspace operation.

When it happens

Trigger: Running `yarn install --focus` from the workspace root directory. Running `--focus` outside any workspace project at all.

Common situations: Developer reads about `--focus` and tries it from the repo root. CI script sets `--focus` globally but runs from root. Migrating from a focused workspace setup and forgetting to `cd` into the package.

Related errors

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