nodejs/node · error · Error

Please provide only one of ${flagList}

Error message

Please provide only one of ${flagList}

What it means

npm resolves flag aliases (e.g. a short and long form, or two legacy names) to a single canonical key. If two or more names from the same alias group are supplied at once, it cannot decide which value wins, so it throws listing the conflicting flags.

Source

Thrown at deps/npm/lib/base-cmd.js:347

    if (this.constructor.definitions && this.constructor.definitions.length > 0) {
      this.#validateFlags(parsed, commandDefinitions, remains)
    }

    // Check for conflicts between main flags and their aliases
    // Also map aliases back to their main keys
    for (const [mainKey, aliases] of Object.entries(aliasMap)) {
      const providedKeys = []
      if (mainKey in parsed) {
        providedKeys.push(mainKey)
      }
      for (const alias of aliases) {
        if (alias in parsed) {
          providedKeys.push(alias)
        }
      }
      if (providedKeys.length > 1) {
        const flagList = providedKeys.map(k => `--${k}`).join(' or ')
        throw new Error(`Please provide only one of ${flagList}`)
      }

      // If an alias was provided, map it to the main key
      if (providedKeys.length === 1 && providedKeys[0] !== mainKey) {
        const aliasKey = providedKeys[0]
        parsed[mainKey] = parsed[aliasKey]
        delete parsed[aliasKey]
      }
    }

    // Only include keys that are defined in commandDefinitions (main keys only)
    const filtered = {}
    for (const def of commandDefinitions) {
      if (def.key in parsed) {
        filtered[def.key] = parsed[def.key]
      }
    }
    return [{ ...defaults, ...filtered }, remains]

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Read the flag list in the message and keep only one of the names, then re-run
2. Search .npmrc (user, global, project) and npm_config_* env for an alias of the same option and remove the duplicate
3. Run with --no-... or the canonical long form only, consulting `npm help config` for the canonical name

Example fix

# before (two names for the same option)
npm publish --tag next --dist-tag next

# after (single canonical flag)
npm publish --tag next

// Before building argv, ensure no two names from the same alias group are present
function hasAliasCollision(provided, aliasGroups) {
  return aliasGroups.some(group => provided.filter(k => group.includes(k)).length > 1)
}

function isSingleAliasGroupUse(providedKeys, aliasGroups) {
  return !hasAliasCollision(providedKeys, aliasGroups)
}

When it happens

Trigger: Passing a flag together with its alias, or two aliases of the same option, in one command. Also triggered by a flag set on the CLI that is also present (under an alias) in .npmrc or npm_config_* env vars in some merged configurations.

Common situations: Copy-pasting flags from different documentation sources; build scripts that concatenate flag lists; legacy aliases still lingering in npmrc.

Related errors

• Cannot use --no-workspaces and --workspace at the same time
• Unknown positional argument: ${extra}
• ${argv[2]} not recognized
• As of npm@5, the npm cache self-heals from corruption issues
• `${baseKey}` is not a valid npm option

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