nodejs/node · error · Error

Workspaces not supported for global packages

Error message

Workspaces not supported for global packages

What it means

Thrown by npm's central command executor when the user passed a workspace option (`--workspaces`/`-ws`, or `--workspace`/`-w`) and the resolved target would operate on global packages. Workspaces are a per-project concept rooted in a local package.json, so combining them with `--global` is contradictory and rejected before the command runs.

Source

Thrown at deps/npm/lib/npm.js:281

      const subcommandPath = [...commandPath, subcommandName]

      return time.start(`command:${subcommandPath.join(':')}`, () =>
        this.execCommandClass(subcommandInstance, subcommandArgs, subcommandPath))
    }

    // No subcommands - execute this command
    if (this.config.get('usage')) {
      return output.standard(commandInstance.usage)
    }

    let execWorkspaces = false
    const hasWsConfig = this.config.get('workspaces') || this.config.get('workspace').length
    // if cwd is a workspace, the default is set to [that workspace]
    const implicitWs = this.config.get('workspace', 'default').length
    // (-ws || -w foo) && (cwd is not a workspace || command is not ignoring implicit workspaces)
    if (hasWsConfig && (!implicitWs || !Command.ignoreImplicitWorkspace)) {
      if (this.global) {
        throw new Error('Workspaces not supported for global packages')
      }
      if (!Command.workspaces) {
        throw Object.assign(new Error('This command does not support workspaces.'), {
          code: 'ENOWORKSPACES',
        })
      }
      execWorkspaces = true
    }

    // Check dev engines if needed
    if (commandInstance.checkDevEngines && !this.global) {
      await commandInstance.checkDevEngines()
    }

    // Execute command with or without definitions
    if (Command.definitions) {
      // config.argv contains the full argv with flags (set by Config in production, by MockNpm in tests)
      // Pass depth so flags() knows how many command names to skip

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Drop the workspace flag(s) when running globally.
2. Drop `-g`/`--global` when operating on workspaces.
3. Audit .npmrc and environment for stale `workspaces`/`global` settings; unset `npm_config_workspaces` in CI scripts.

Example fix

// before
npm install -g --workspace=app lodash
// after
npm install --workspace=app lodash   // local
// or
npm install -g lodash               // global, no workspace

const hasWs = npm.config.get('workspaces') || npm.config.get('workspace').length
if (hasWs && npm.config.get('global')) {
  throw new Error('Workspaces cannot be combined with global mode')
}

const isWorkspaceGlobalConflict = (cfg) =>
  (cfg.get('workspaces') || cfg.get('workspace').length > 0) && cfg.get('global')

try {
  await npm.exec(cmd, args)
} catch (err) {
  if (/Workspaces not supported for global/i.test(err.message)) {
    // drop either the -ws/-w flag or the -g flag based on user intent, then retry
  } else { throw err }
}

When it happens

Trigger: `npm install -g --workspace=foo pkg`, or any command under `npm -g -ws`, or having `global=true` plus `workspaces=true` in config. The guard fires when hasWsConfig is true and (!implicitWs || !ignoreImplicitWorkspace).

Common situations: An .npmrc sets `workspaces=true` and a script invokes `npm -g`; CI that sets both flags via env vars; aliasing `-ws` globally and forgetting to disable it for global operations.

Related errors

• `${baseKey}` is not a valid npm option
• Cannot use view command in global mode.
• No workspaces found${msg}
• Invalid URL: ${url}
• expected opts.methods to be an array, got ${typeof methods}

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/1c1fd011051a0feb. Report an issue: GitHub.