nodejs/node · error · Error

`${baseKey}` is not a valid npm option

Error message

`${baseKey}` is not a valid npm option

What it means

`npm config set <key> <val>` checks each key against npm's config definitions (and the nerf-dart auth-key allowlist). A key whose base segment (after the last ':') is neither a known option nor a nerf-dart is rejected as invalid, preventing silent typos that would otherwise write junk into .npmrc.

Source

Thrown at deps/npm/lib/commands/config.js:170

      case 'fix':
        await this.fix()
        break
      default:
        throw this.usageError()
    }
  }

  async set (args) {
    if (!args.length) {
      throw this.usageError()
    }

    const where = this.npm.flatOptions.location
    for (const [key, val] of Object.entries(keyValues(args))) {
      log.info('config', 'set %j %j', key, val)
      const baseKey = key.split(':').pop()
      if (!this.npm.config.definitions[baseKey] && !nerfDarts.includes(baseKey)) {
        throw new Error(`\`${baseKey}\` is not a valid npm option`)
      }
      const deprecated = this.npm.config.definitions[baseKey]?.deprecated
      if (deprecated) {
        throw new Error(
          `The \`${baseKey}\` option is deprecated, and cannot be set in this way${deprecated}`
        )
      }

      if (val === '') {
        this.npm.config.delete(key, where)
      } else {
        this.npm.config.set(key, val, where)
      }

      if (!this.npm.config.validate(where)) {
        log.warn('config', 'omitting invalid config values')
      }
    }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Check the canonical list with `npm config list -l` or `npm help config` and use the exact key
2. Fix the typo in the key name
3. For registry-scoped auth, use the nerf-dart form (//<registry>/:_authToken) which is allowed

Example fix

# before
npm config set regsitry https://registry.npmjs.org

# after
npm config set registry https://registry.npmjs.org

const npm = require('npm/package.json') // or your npm instance's config
const definitions = require('@npmcli/config/lib/definitions/index.js').definitions // path may vary
const nerfDarts = [] // nerf-dart keys are dynamic
function isValidConfigKey(key) {
  const base = key.split(':').pop()
  return Boolean(definitions[base]) || /^\/\/.+\//:/./.test(key) || nerfDarts.includes(base)
}

function isKnownNpmOption(key, definitions) {
  return Object.prototype.hasOwnProperty.call(definitions, key.split(':').pop())
}

When it happens

Trigger: Typo'd option name, an option removed in this npm version, or a key that is neither a defined config option nor an auth-scoped nerf-dart like //registry.example.org/:_authToken.

Common situations: Following an outdated blog post with a renamed/removed option; misspelling (e.g. 'regsitry'); CI that writes dynamic keys.

Related errors

• The `${baseKey}` option is deprecated, and cannot be set in
• The ${key} option is protected, and cannot be retrieved in t
• Tag name must not be a valid SemVer range: ${defaultTag.trim
• Workspaces not supported for global packages
• Invalid URL: ${url}

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